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Foreword 


1  ISO  (the  International  Organization  for  Standardization)  and  IEC  (the  Interna- 

2  tional  Electrotechnical  Commission)  together  form  a  system  for  worldwide  stan- 

3  dardization  as  a  whole.  National  bodies  that  are  members  of  ISO  or  IEC  partici- 

4  pate  in  the  development  of  International  Standards  through  technical  committees 

5  established  by  the  respective  organization  to  deal  with  particular  fields  of  techni- 

6  cal  activity.  ISO  and  IEC  technical  committees  collaborate  in  fields  of  mutual 

7  interest.  Other  international  organizations,  governmental  and  nongovernmental, 

8  in  liaison  with  ISO  and  IEC,  also  take  part  in  the  work. 

9  In  the  field  of  information  technology,  ISO  and  IEC  have  established  a  joint  techni- 

10  cal  committee,  ISO/IEC  JTC  1.  Draft  International  Standards  adopted  by  the  joint 

n  technical  committee  are  circulated  to  national  bodies  for  approval  before  their 

12  acceptance  as  International  Standards.  They  are  approved  in  accordance  with 

13  procedures  requiring  at  least  75%  approval  by  the  national  bodies  voting. 

14  International  Standard  ISO/IEC  9945-1:  1990  was  prepared  by  Joint  Technical 

15  Committee  ISO/IEC  JTC  1,  Information  technology. 

16  ISO/IEC  9945  consists  of  the  following  parts,  under  the  general  title  Information 

17  technology — Portable  operating  system  interface  (POSIX) : 

is  —  Part  1:  System  application  program  interface  (API)  [C  language] 

19  —  Part  2:  Shell  and  utilities  (under  development) 

20  —  Part  3:  System  administration  (under  development) 

21  Annexes  A  to  E  of  ISO/IEC  9945-1  are  provided  for  information  only. 


International  Organization  for  Standardization/International  Electrotechnical  Commission 
Case  postale  56  .  CH-1211  Geneve  20  •  Switzerland 


viii 


Foreword 


Introduction 


(This  Introduction  is  not  a  normative  part  of  ISO/IEC  9945-1  Information  technology — Portable 
operating  system  interface  (POSIX) — Part  1:  System  application  programming  interface  (API) 
[C  Language],  but  is  included  for  information  only.) 


1  The  purpose  of  this  part  of  ISO/IEC  9945  is  to  define  a  standard  operating  system 

2  interface  and  environment  based  on  the  UNIX1)  Operating  System  documentation 

3  to  support  application  portability  at  the  source  level.  This  is  intended  for  systems 

4  implementors  and  applications  software  developers. 

5  Initially, 2)  the  focus  of  this  part  of  ISO/IEC  9945  is  to  provide  standardized  ser- 

6  vices  via  a  C  language  interface.  Future  revisions  are  expected  to  contain  bind- 

7  ings  for  other  programming  languages  as  well  as  for  the  C  language.  This  will  be 

8  accomplished  by  breaking  this  part  of  ISO/IEC  9945  into  multiple  portions — one 

9  defining  core  requirements  independent  of  any  programming  language,  and  oth- 

10  ers  composed  of  programming  language  bindings. 

n  The  core  requirements  portion  will  define  a  set  of  required  services  common  to 

12  any  programming  language  that  can  be  reasonably  expected  to  form  a  language 

13  binding  to  this  part  of  ISO/IEC  9945.  These  services  will  be  described  in  terms  of 

14  functional  requirements  and  will  not  define  programming  language-dependent 

15  interfaces.  Language  bindings  will  consist  of  two  major  parts.  One  will  contain 

16  the  programming  language’s  standardized  interface  for  accessing  the  core  services 

17  defined  in  the  programming  language-independent  core  requirements  section  of 

18  this  part  of  ISO/IEC  9945.  The  other  will  contain  a  standardized  interface  for 

19  language-specific  services.  Any  implementation  claiming  conformance  to  this  part 

20  of  ISO/IEC  9945  with  any  language  binding  will  be  required  to  comply  with  both 

21  sections  of  the  language  binding. 

22  Within  this  document,  the  term  “POSIX.!”  refers  to  this  part  of  ISO/IEC  9945 

23  itself. 


24 

25 

26 

27 

28 
29 


Organization  of  This  Part  of  ISO/EEC  9945 

This  part  of  ISO/IEC  9945  is  divided  into  four  elements: 

(1)  Statement  of  scope  and  list  of  normative  references  (Section  1) 

(2)  Definitions  and  global  concepts  (Section  2) 

(3)  The  various  interface  facilities  (Sections  3  through  9) 

(4)  Data  interchange  format  (Section  10) 


30  1)  UNIX  is  a  registered  trademark  of  UNIX  System  Laboratories  in  the  U.S.  and  other  countries. 

31  2)  The  vertical  rules  in  the  right  margin  depict  technical  or  significant  non-editorial  changes  from 

32  IEEE  Std  1003.1-1988  to  IEEE  Std  1003.1-1990.  A  vertical  rule  beside  an  empty  line  indicates 

33  deleted  text. 


Introduction 


IX 


34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 

61 

62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 


Most  of  the  sections  describe  a  single  service  interface.  The  C  Language  binding 
for  the  service  interface  is  given  in  the  subclause  labeled  Synopsis.  The  Descrip¬ 
tion  subclause  provides  a  specification  of  the  operation  performed  by  the  service 
interface.  Some  examples  may  be  provided  to  illustrate  the  interfaces  described. 

In  most  cases  there  are  also  Returns  and  Errors  subclauses  specifying  return 
values  and  possible  error  conditions.  References  are  used  to  direct  the  reader  to 
other  related  sections.  Additional  material  to  complement  sections  in  this  part  of 
ISO/IEC  9945  may  be  found  in  the  Rationale  and  Notes,  Annex  B.  This  annex  pro¬ 
vides  historical  perspectives  into  the  technical  choices  made  by  the  developers  of 
this  part  of  ISO/IEC  9945.  It  also  provides  information  to  emphasize  consequences 
of  the  interfaces  described  in  the  corresponding  section  of  this  part  of 
ISO/IEC  9945. 

Informative  annexes  are  not  part  of  the  standard  and  are  provided  for  information 
only.  (There  is  a  type  of  annex  called  “normative”  that  is  part  of  a  standard  and 
imposes  requirements,  but  there  are  currently  no  such  normative  annexes  in  this 
part  of  ISO/IEC  9945.)  They  are  provided  for  guidance  and  to  help  understanding. 

In  publishing  this  part  of  ISO/IEC  9945,  its  developers  simply  intend  to  provide  a 
yardstick  against  which  various  operating  system  implementations  can  be  meas¬ 
ured  for  conformance.  It  is  not  the  intent  of  the  developers  to  measure  or  rate  any 
products,  to  reward  or  sanction  any  vendors  of  products  for  conformance  or  lack  of 
conformance  to  this  part  of  ISO/IEC  9945,  or  to  attempt  to  enforce  this  part  of 
ISO/IEC  9945  by  these  or  any  other  means.  The  responsibility  for  determining  the 
degree  of  conformance  or  lack  thereof  with  this  part  of  ISO/IEC  9945  rests  solely 
with  the  individual  who  is  evaluating  the  product  claiming  to  be  in  conformance 
with  this  part  of  ISO/IEC  9945. 

Base  Documents 

The  various  interface  facilities  described  herein  are  based  on  the  1984  /  usr/ group 
Standard  derived  and  published  by  the  UniForum  (formerly  /usr/group)  Stan-  | 
dards  Committee.  The  1984  /usr /group  Standard  and  this  part  of  ISO/IEC  9945 
are  largely  based  on  UNIX  Seventh  Edition,  UNIX  System  III,  UNIX  System  V, 
4.2BSD,  and  4.3BSD  documentation, 3)  but  wherever  possible,  compatibility  with 
other  systems  derived  from  the  UNIX  operating  system,  or  systems  compatible 
with  that  system,  has  been  maintained. 

Background  I 

The  developers  of  POSIX.1  represent  a  cross-section  of  hardware  manufacturers,  | 
vendors  of  operating  systems  and  other  software  development  tools,  software 
designers,  consultants,  academics,  authors,  applications  programmers,  and  oth¬ 
ers.  In  the  course  of  their  deliberations,  the  developers  reviewed  related  Ameri-  | 
can  and  international  standards,  both  published  and  in  progress.  I 

Conceptually,  POSIX.1  describes  a  set  of  fundamental  services  needed  for  the  | 
efficient  construction  of  application  programs.  Access  to  these  services  has  been  | 


3)  The  IEEE  is  grateful  to  both  AT&T  and  UniForum  for  permission  to  use  their  materials. 
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provided  by  defining  an  interface,  using  the  C  programming  language,  that  estab¬ 
lishes  standard  semantics  and  syntax.  Since  this  interface  enables  application 
writers  to  write  portable  applications — it  was  developed  with  that  goal  in  mind — 
it  has  been  designated  POSIX,4)  an  acronym  for  Portable  Operating  System 
Interface. 

Although  originated  to  refer  to  IEEE  Std  1003.1-1988,  the  name  POSIX  more  | 
correctly  refers  to  a  family  of  related  standards:  IEEE  1003.rc  and  the  parts  of  | 
International  Standard  ISO/IEC  9945.  In  earlier  editions  of  the  IEEE  standard,  | 
the  term  POSIX  was  used  as  a  synonym  for  IEEE  Std  1003.1-1988.  A  preferred 
term,  POSIX.1,  emerged.  This  maintained  the  advantages  of  readability  of  the  | 
symbol  “POSIX”  without  being  ambiguous  with  the  POSIX  family  of  standards.  | 

Audience 

The  intended  audience  for  ISO/IEC  9945  is  all  persons  concerned  with  an 
industry-wide  standard  operating  system  based  on  the  UNIX  system.  This 
includes  at  least  four  groups  of  people: 

(1)  Persons  buying  hardware  and  software  systems; 

(2)  Persons  managing  companies  that  are  deciding  on  future  corporate  com¬ 
puting  directions; 

(3)  Persons  implementing  operating  systems,  and  especially 

(4)  Persons  developing  applications  where  portability  is  an  objective. 

Purpose 

Several  principles  guided  the  development  of  this  part  of  ISO/IEC  9945:  | 

Application  Oriented 

The  basic  goal  was  to  promote  portability  of  application  programs  across  | 
UNIX  system  environments  by  developing  a  clear,  consistent,  and  unam¬ 
biguous  standard  for  the  interface  specification  of  a  portable  operating 
system  based  on  the  UNIX  system  documentation.  This  part  of 
ISO/IEC  9945  codifies  the  common,  existing  definition  of  the  UNIX  sys¬ 
tem.  There  was  no  attempt  to  define  a  new  system  interface. 

Interface,  Not  Implementation 

This  part  of  ISO/IEC  9945  defines  an  interface,  not  an  implementation. 

No  distinction  is  made  between  library  functions  and  system  calls:  both 
are  referred  to  as  functions.  No  details  of  the  implementation  of  any 
function  are  given  (although  historical  practice  is  sometimes  indicated 
in  Annex  B).  Symbolic  names  are  given  for  constants  (such  as  signals 
and  error  numbers)  rather  than  numbers. 


4)  The  name  POSIX  was  suggested  by  Richard  Stallman.  It  is  expected  to  be  pronounced  pahz-icks, 
as  in  positive,  not  poh-six,  or  other  variations.  The  pronunciation  has  been  published  in  an 
attempt  to  promulgate  a  standardized  way  of  referring  to  a  standard  operating  system  interface. 
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Source,  Not  Object,  Portability 

This  part  of  ISO/IEC  9945  has  been  written  so  that  a  program  written 
and  translated  for  execution  on  one  conforming  implementation  may 
also  be  translated  for  execution  on  another  conforming  implementation. 
This  part  of  ISO/IEC  9945  does  not  guarantee  that  executable  (object  or 
binary)  code  will  execute  under  a  different  conforming  implementation 
than  that  for  which  it  was  translated,  even  if  the  underlying  hardware 
is  identical.  However,  few  impediments  were  placed  in  the  way  of 
binary  compatibility,  and  some  remarks  on  this  are  found  in  Annex  B. 
See  B.  1.3. 1.1  and  B.4.8. 

The  C  Language 

This  part  of  ISO/IEC  9945  is  written  in  terms  of  the  standard  C  language 
as  specified  in  the  C  Standard  {2}.5 6)  See  B.1.3  and  B. 1.1.1. 

No  Super-User,  No  System  Administration 

There  was  no  intention  to  specify  all  aspects  of  an  operating  system. 
System  administration  facilities  and  functions  are  excluded  from 
POSIX.1,  and  functions  usable  only  by  the  super-user  have  not  been 
included.  Annex  B  notes  several  such  instances.  Still,  an  implementa¬ 
tion  of  the  standard  interface  may  also  implement  features  not  in  this 
part  of  ISO/IEC  9945;  see  1.3.1. 1.  This  part  of  ISO/IEC  9945  is  also  not 
concerned  with  hardware  constraints  or  system  maintenance. 

Minimal  Interface,  Minimally  Defined 

In  keeping  with  the  historical  design  principles  of  the  UNIX  system, 
POSIX.1  is  as  minimal  as  possible.  For  example,  it  usually  specifies  only 
one  set  of  functions  to  implement  a  capability.  Exceptions  were  made  in 
some  cases  where  long  tradition  and  many  existing  applications 
included  certain  functions,  such  as  creati).  In  such  cases,  as  throughout 
POSIX1,  redundant  definitions  were  avoided:  creati)  is  defined  as  a  spe¬ 
cial  case  of  open{).  Redundant  functions  or  implementations  with  less 
tradition  were  excluded. 

Broadly  Implementable 

The  developers  of  POSIX.1  endeavored  to  make  all  specified  functions 
implementable  across  a  wide  range  of  existing  and  potential  systems, 
including: 

(1)  All  of  the  current  major  systems  that  are  ultimately  derived  from 
the  original  UNIX  system  code  (Version  7  or  later) 

(2)  Compatible  systems  that  are  not  derived  from  the  original  UNIX 
system  code 
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5)  The  number  in  braces  corresponds  to  those  of  the  references  in  1.2  (or  the  bibliographic  entry  in 
Annex  A  if  the  number  is  preceded  by  the  letter  B). 
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(3)  Emulations  hosted  on  entirely  different  operating  systems 

(4)  Networked  systems 

(5)  Distributed  systems 

(6)  Systems  running  on  a  broad  range  of  hardware 

No  direct  references  to  this  goal  appear  in  this  part  of  ISO/IEC  9945,  but 
some  results  of  it  are  mentioned  in  Annex  B. 

Minimal  Changes  to  Historical  Implementations 

There  are  no  known  historical  implementations  that  will  not  have  to 
change  in  some  area  to  conform  to  this  part  of  ISO/IEC  9945,  and  in  a 
few  areas  POSIX.l  does  not  exactly  match  any  existing  system  interface 
(for  example,  see  the  discussion  of  0_N0NBL0CK  in  B.6).  Nonetheless, 
there  is  a  set  of  functions,  types,  definitions,  and  concepts  that  form  an 
interface  that  is  common  to  most  historical  implementations.  POSIX.1 
specifies  that  common  interface  and  extends  it  in  areas  where  there  has 
historically  been  no  consensus,  preferably 

(1)  By  standardizing  an  interface  like  one  in  an  historical  implemen¬ 
tation;  e.g.,  directories,  or; 

(2)  By  specifying  an  interface  that  is  readily  implementable  in  terms 
of,  and  backwards  compatible  with,  historical  implementations, 
such  as  the  extended  tar  format  in  10.1.1,  or; 

(3)  By  specifying  an  interface  that,  when  added  to  an  historical  imple¬ 
mentation,  will  not  conflict  with  it,  like  B.6. 

Required  changes  to  historical  implementations  have  been  kept  to  a 
minimum,  but  they  do  exist,  and  Annex  B  points  out  some  of  them. 

POSIX.1  is  specifically  not  a  codification  of  a  particular  vendor’s  product. 

It  is  similar  to  the  UNIX  system,  but  it  is  not  identical  to  it. 

It  should  be  noted  that  implementations  will  have  different  kinds  of 
extensions.  Some  will  reflect  “historical  usage”  and  will  be  preserved  for 
execution  of  pre-existing  applications.  These  functions  should  be  con¬ 
sidered  “obsolescent”  and  the  standard  functions  used  for  new  applica¬ 
tions.  Some  extensions  will  represent  functions  beyond  the  scope  of 
POSIX.1.  These  need  to  be  used  with  careful  management  to  be  able  to 
adapt  to  future  POSIX.1  extensions  and/or  port  to  implementations  that 
provide  these  services  in  a  different  manner. 

Minimal  Changes  to  Existing  Application  Code 

A  goal  of  POSIX.1  was  to  minimize  additional  work  for  the  developers  of  | 
applications.  However,  because  every  known  historical  implementation  | 
will  have  to  change  at  least  slightly  to  conform,  some  applications  will 
have  to  change.  Annex  B  points  out  the  major  places  where  POSIX.1 
implies  such  changes. 
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Related  Standards  Activities 


Activities  to  extend  this  part  of  ISO/IEC  9945  to  address  additional  requirements 
are  in  progress,  and  similar  efforts  can  be  anticipated  in  the  future. 

The  following  areas  are  under  active  consideration  at  this  time,  or  are  expected  to 
become  active  in  the  near  future  :6) 

(1)  Language-independent  service  descriptions  of  this  part  of  ISO/IEC  9945 

(2)  C,  Ada,  and  FORTRAN  Language  bindings  to  (1) 

(3)  Shell  and  Utility  facilities 

(4)  Verification  testing  methods 

(5)  Realtime  facilities 

(6)  Secure/Trusted  System  considerations 

(7)  Network  interface  facilities 

(8)  System  Administration 

(9)  Graphical  User  Interfaces 

(10)  Profiles  describing  application-  or  user-specific  combinations  of  Open  Sys¬ 
tems  standards  for:  supercomputing,  multiprocessor,  and  batch  exten¬ 
sions;  transaction  processing;  realtime  systems;  and  multiuser  systems 
based  on  historical  models 

(11)  An  overall  guide  to  POSIX-based  or  related  Open  Systems  standards  and 
profiles 

Extensions  are  approved  as  “amendments”  or  “revisions”  to  this  document,  follow¬ 
ing  the  IEEE  and  ISO/IEC  Procedures. 

Approved  amendments  are  published  separately  until  the  full  document  is 
reprinted  and  such  amendments  are  incorporated  in  their  proper  positions. 

If  you  have  interest  in  participating  in  the  TCOS  working  groups  addressing  these 
issues,  please  send  your  name,  address,  and  phone  number  to  the  Secretary,  IEEE 
Standards  Board,  Institute  of  Electrical  and  Electronics  Engineers,  Inc.,  P.O.  Box 
1331,  445  Hoes  Lane,  Piscataway,  NJ  08855-1331,  and  ask  to  have  this  forwarded 
to  the  chairperson  of  the  appropriate  TCOS  working  group.  If  you  have  interest  in 
participating  in  this  work  at  the  international  level,  contact  your  ISO/IEC  national 
body. 


6)  A  Standards  Status  Report  that  lists  all  current  IEEE  Computer  Society  standards  projects  is 
available  from  the  IEEE  Computer  Society,  1730  Massachusetts  Avenue  NW,  Washington,  DC 
20036-1903;  Telephone:  +1  202  371-0101;  FAX:  +1  202  728-9614.  Working  drafts  of  POSK 
standards  under  development  are  also  available  from  this  office. 
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INTERNATIONAL  STANDARD 


ISO/IE C  9945-1:  1990 


Information  technology — Portable  operating 
system  interface  (POSIX) — Part  1:  System 
application  programming  interface  (API) 

[C  Language] 


Section  1:  General 


1.1  Scope 

This  part  of  ISO/IEC  9945  defines  a  standard  operating  system  interface  and 
environment  to  support  application  portability  at  the  source-code  level.  It  is 
intended  to  be  used  by  both  application  developers  and  system  implementors. 

This  part  of  ISO/IEC  9945  comprises  four  major  components: 

(1)  Terminology,  concepts,  and  definitions  and  specifications  that  govern 
structures,  headers,  environment  variables,  and  related  requirements 

(2)  Definitions  for  system  service  interfaces  and  subroutines 

(3)  Language- specific  system  services  for  the  C  programming  language 

(4)  Interface  issues,  including  portability,  error  handling,  and  error  recovery 
The  following  areas  are  outside  of  the  scope  of  this  part  of  ISO/IEC  9945: 

(1)  User  interface  (shell)  and  associated  commands 

(2)  Networking  protocols  and  system  call  interfaces  to  those  protocols 

(3)  Graphics  interfaces 

(4)  Database  management  system  interfaces 

(5)  Record  I/O  considerations 
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(6)  Object  or  binary  code  portability 

(7)  System  configuration  and  resource  availability 

(8)  The  behavior  of  system  services  on  systems  supporting  concurrency 
within  a  single  process 

This  part  of  ISO/IEC  9945  describes  the  external  characteristics  and  facilities  that 
are  of  importance  to  applications  developers,  rather  than  the  internal  construc¬ 
tion  techniques  employed  to  achieve  these  capabilities.  Special  emphasis  is 
placed  on  those  functions  and  facilities  that  are  needed  in  a  wide  variety  of  com¬ 
mercial  applications. 

This  part  of  ISO/IEC  9945  has  been  defined  exclusively  at  the  source-code  level. 
The  objective  is  that  a  Strictly  Conforming  POSIX.l  Application  source  program 
can  be  translated  to  execute  on  a  conforming  implementation. 


1.2  Normative  References 

The  following  standards  contain  provisions  which,  through  references  in  this  text, 
constitute  provisions  of  this  part  of  ISO/IEC  9945.  At  the  time  of  publication,  the 
editions  indicated  were  valid.  All  standards  are  subject  to  revision,  and  parties  to 
agreements  based  on  this  part  of  this  International  Standard  are  encouraged  to 
investigate  the  possibility  of  applying  the  most  recent  editions  of  the  standards 
listed  below.  Members  of  IEC  and  ISO  maintain  registers  of  currently  valid  Inter¬ 
national  Standards. 

{1}  ISO/IEC  646:  1983, Information  processing — ISO  7-bit  coded  character  set 
for  information  interchange. 

{2}  ISO/IEC  9899:  . . .  ,1 2)  Information  technology — Programming  languages — C. 


1.3  Conformance 


1.3.1  Implementation  Conformance 

1.3. 1.1  Requirements 

A  conforming  implementation  shall  meet  all  of  the  following  criteria: 


1)  Under  revision.  (This  notation  is  meant  to  explicitly  reference  the  1990  Draft  International 
Standard  version  of  ISO/IEC  646.) 

ISO/IEC  documents  can  be  obtained  from  the  ISO  office,  1,  rue  de  Varembe,  Case  Postale  56,  CH- 
1211,  Geneve  20,  Switzerland/Suisse. 

2)  To  be  approved  and  published. 
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(1)  The  system  shall  support  all  required  interfaces  defined  within  this  part 
of  ISO/IEC  9945.  These  interfaces  shall  support  the  functional  behavior 
described  herein. 

(2)  The  system  may  provide  additional  functions  or  facilities  not  required  by 
this  part  of  ISO/IEC  9945.  Nonstandard  extensions  should  be  identified 
as  such  in  the  system  documentation.  Nonstandard  extensions,  when 
used,  may  change  the  behavior  of  functions  or  facilities  defined  by  this 
part  of  ISO/IEC  9945.  The  conformance  document  shall  define  an  | 
environment  in  which  an  application  can  be  run  with  the  behavior  | 
specified  by  the  standard.  In  no  case  shall  such  an  environment  require 
modification  of  a  Strictly  Conforming  POSIX.l  Application. 

1.3. 1.2  Documentation 

A  conformance  document  with  the  following  information  shall  be  available  for  an 
implementation  claiming  conformance  to  this  part  of  ISO/IEC  9945.  The  confor¬ 
mance  document  shall  have  the  same  structure  as  this  part  of  ISO/IEC  9945,  with 
the  information  presented  in  the  appropriately  numbered  sections,  clauses,  and 
subclauses.  The  conformance  document  shall  not  contain  information  about 
extended  facilities  or  capabilities  outside  the  scope  of  this  part  of  ISO/IEC  9945. 

The  conformance  document  shall  contain  a  statement  that  indicates  the  full 
name,  number,  and  date  of  the  standard  that  applies.  The  conformance  document 
may  also  list  international  software  standards  that  are  available  for  use  by  a  Con¬ 
forming  POSIX.1  Application.  Applicable  characteristics  where  documentation  is 
required  by  one  of  these  standards,  or  by  standards  of  government  bodies,  may 
also  be  included. 

The  conformance  document  shall  describe  the  limit  values  found  in  the  | 
<limits.h>  and  <unistd.h>  headers,  stating  values,  the  conditions  under 
which  those  values  may  change,  and  the  limits  of  such  variations,  if  any. 

The  conformance  document  shall  describe  the  behavior  of  the  implementation  for 
all  implementation-defined  features  defined  in  this  part  of  ISO/IEC  9945.  This 
requirement  shall  be  met  by  listing  these  features  and  providing  either  a  specific  | 
reference  to  the  system  documentation  or  providing  full  syntax  and  semantics  of  | 
these  features.  The  conformance  document  may  specify  the  behavior  of  the  imple-  | 
mentation  for  those  features  where  this  part  of  ISO/IEC  9945  states  that  imple-  | 
mentations  may  vary  or  where  features  are  identified  as  undefined  or  unspecified.  | 

No  specifications  other  than  those  described  in  this  part  of  ISO/IEC  9945  shall  be  | 
present  in  the  conformance  document. 

The  phrases  “shall  document”  or  “shall  be  documented”  in  this  part  of  | 
ISO/IEC  9945  mean  that  documentation  of  the  feature  shall  appear  in  the  confor-  | 
mance  document,  as  described  previously,  unless  the  system  documentation  is  | 
explicitly  mentioned.  | 

The  system  documentation  should  also  contain  the  information  found  in  the  con-  | 
formance  document. 
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91  1.3. 1.3  Conforming  Implementation  Options 

92  The  following  symbolic  constants,  described  in  the  subclauses  indicated,  reflect  | 

93  implementation  options  for  this  part  of  ISO/IEC  9945  that  could  warrant  require- 

94  ment  by  Conforming  POSIX.1  Applications,  or  in  specifications  of  conforming  sys- 

95  terns,  or  both: 

96  {NGROUPS_MAX}  Multiple  groups  option  (in  2.8.3) 

97  {_POSIX_JOB_CONTROL}  Job  control  option  (in  2.9.3) 

98  {_POSIX_CHOWN_RESTRICTED}  Administrative/security  option  (in  2.9.4) 

99  The  remaining  symbolic  constants  in  2.9.3  and  2.9.4  are  useful  for  testing  pur- 

100  poses  and  as  a  guide  to  applications  on  the  types  of  behaviors  they  need  to  be  able 

101  to  accommodate.  They  do  not  reflect  sufficient  functional  difference  to  warrant 

102  requirement  by  Conforming  POSIX.1  Applications  or  to  distinguish  between  con- 

103  forming  implementations. 

104  In  the  cases  where  omission  of  an  option  would  cause  functions  described  by  this 

105  part  of  ISO/IEC  9945  to  not  be  defined,  an  implementation  shall  provide  a  function 

106  that  is  callable  with  the  syntax  defined  in  this  part  of  ISO/IEC  9945,  even  though 

107  in  an  instance  of  the  implementation  the  function  may  always  do  nothing  but 

108  return  an  error. 

109  1.3.2  Application  Conformance 

no  All  applications  claiming  conformance  to  this  part  of  ISO/IEC  9945  shall  use  only 

111  language-dependent  services  for  the  C  programming  language  described  in  1.3.3 

112  and  shall  fall  within  one  of  the  following  categories: 

113  1.3.2.1  Strictly  Conforming  POSIX.1  Application 

114  A  Strictly  Conforming  POSIX.1  Application  is  an  application  that  requires  only  the 

115  facilities  described  in  this  part  of  ISO/IEC  9945  and  the  applicable  language  stan- 

116  dards.  Such  an  application  shall  accept  any  behavior  described  in  this  part  of 

117  ISO/IEC  9945  as  unspecified  or  implementation-defined,  and  for  symbolic  con-  | 

ns  stants,  shall  accept  any  value  in  the  range  permitted  by  this  part  of  ISO/IEC  9945. 

119  Such  applications  are  permitted  to  adapt  to  the  availability  of  facilities  whose 

120  availability  is  indicated  by  the  constants  in  2.8  and  2.9. 

121  1.3.2.2  Conforming  POSIX.1  Application 

122  1.3.2.2.1  ISO/IEC  Conforming  POSIX.1  Application  | 

123  An  ISO/IEC  Conforming  POSIX.1  Application  is  an  application  that  uses  only  the  | 

124  facilities  described  in  this  part  of  ISO/IEC  9945  and  approved  Conforming  | 

125  Language  bindings  for  any  ISO  or  IEC  standard.  Such  an  application  shall  | 

126  include  a  statement  of  conformance  that  documents  all  options  and  limit  depen-  | 

127  dencies,  and  all  other  ISO  or  IEC  standards  used. 
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1.3.2.2.2  <National  Body>  Conforming  POSEX.1  Application 

A  <National  Body>  Conforming  POSIX.1  Application  differs  from  an  ISO/IEC  Con¬ 
forming  POSIX.l  Application  in  that  it  also  may  use  specific  standards  of  a  single 
ISO/IEC  member  body  referred  to  here  as  “<National  Body>.”  Such  an  application 
shall  include  a  statement  of  conformance  that  documents  all  options  and  limit 
dependencies,  and  all  other  <National  Body>  standards  used. 

1. 3.2.3  Conforming  POSIX.1  Application  Using  Extensions 

A  Conforming  POSIX.1  Application  Using  Extensions  is  an  application  that  differs 
from  a  Conforming  POSIX.1  Application  only  in  that  it  uses  nonstandard  facilities 
that  are  consistent  with  this  part  of  ISO/IEC  9945.  Such  an  application  shall  fully 
document  its  requirements  for  these  extended  facilities,  in  addition  to  the  docu¬ 
mentation  required  of  a  Conforming  POSIX.1  Application.  A  Conforming  POSIX.1 
Application  Using  Extensions  shall  be  either  an  ISO/IEC  Conforming  POSIX.1 
Application  Using  Extensions  or  a  <National  Body>  Conforming  POSIX.1  Applica¬ 
tion  Using  Extensions  (see  1.3.2. 2.1  and  1.3.2.2.2). 


1.3.3  Language-Dependent  Services  for  the  C  Programming  Language 

Parts  of  ISO/IEC  9899  {2}  (hereinafter  referred  to  as  the  “C  Standard  {2}”)  will  be  | 
referenced  to  describe  requirements  also  mandated  by  this  part  of  ISO/IEC  9945. 
The  sections  of  the  C  Standard  {2}  referenced  to  describe  requirements  for  this 
part  of  ISO/IEC  9945  are  specified  in  Section  8.  Section  8  also  sets  forth  additions 
and  amplifications  to  the  referenced  sections  of  the  C  Standard  {2}.  Any  imple¬ 
mentation  claiming  conformance  to  this  part  of  ISO/IEC  9945  with  the  C  Language 
Binding  shall  provide  the  facilities  referenced  in  Section  8,  along  with  any  addi¬ 
tions  and  amplifications  Section  8  requires. 

Although  this  part  of  ISO/IEC  9945  references  parts  of  the  C  Standard  {2}  to 
describe  some  of  its  own  requirements,  conformance  to  the  C  Standard  {2}  is 
unnecessary  for  conformance  to  this  part  of  ISO/IEC  9945.  Any  C  language  imple¬ 
mentation  providing  the  facilities  stipulated  in  Section  8  may  claim  conformance;  | 
however,  it  shall  clearly  state  that  its  C  language  does  not  conform  to  the  | 
C  Standard  {2}. 

1.3.3.1  Types  of  Conformance 

Implementations  claiming  conformance  to  this  part  of  ISO/IEC  9945  with  the  C 
Language  Binding  shall  claim  one  of  two  types  of  conformance — conformance  to  | 
POSIX.1,  C  Language  Binding  (C  Standard  Language-Dependent  System  Sup-  | 
port),  or  to  POSIX.l,  C  Language  Binding  (Common-Usage  C  Language-Dependent  | 
System  Support). 

1.3.3.2  C  Standard  Language-Dependent  System  Support 

Implementors  shall  meet  the  requirements  of  Section  8  using  for  reference  the 
C  Standard  {2}.  Implementors  shall  clearly  document  the  version  of  the 
C  Standard  {2}  referenced  in  fulfilling  the  requirements  of  Section  8. 
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Implementors  seeking  to  claim  conformance  using  the  C  Standard  {2}  shall  claim  | 
conformance  to  POSIX.1,  C  Language  Binding  (C  Standard  Language-Dependent  | 
System  Support).  | 

1.3.3.3  Common-Usage  C  Language-Dependent  System  Support 

Implementors,  instead  of  referencing  the  C  Standard  {2},  shall  provide  the  rou¬ 
tines  and  support  required  in  Section  8  using  common  usage  as  guidance.  Imple¬ 
mentors  shall  meet  all  the  requirements  of  Section  8  except  where  references  are 
made  to  the  C  Standard  {2}.  In  places  where  the  C  Standard  {2}  is  referenced, 
implementors  shall  provide  equivalent  support  in  a  manner  consistent  with  com¬ 
mon  usage  of  the  C  programming  language.  Implementors  shall  document,  in  | 
Section  8  of  the  conformance  document,  all  differences  between  the  interface  pro-  | 
vided  and  the  interface  that  would  have  been  provided  had  the  C  Standard  {2}  | 

been  implemented  instead  of  common  usage.  Implementors  shall  clearly  docu-  | 
ment  the  version  of  the  C  Standard  {2}  referenced  in  documenting  interface  differ¬ 
ences  and  should  issue  updates  on  differences  for  all  new  versions  of  the 
C  Standard  {2}. 


Where  a  function  has  been  introduced  by  the  C  Standard  {2},  and  thus  there  is  no 
common-usage  referent  for  it,  if  the  function  is  implemented,  it  shall  be  imple¬ 
mented  as  described  in  the  C  Standard  {2}.  If  the  function  is  not  implemented,  it 
shall  be  documented  as  a  difference  from  the  C  Standard  {2}  as  required  above. 


1.3.4  Other  C  Language-Related  Specifications 

The  following  rules  apply  to  the  usage  of  C  language  library  functions;  each  of  the 
statements  in  this  subclause  applies  to  the  detailed  function  descriptions  in  Sec¬ 
tions  3  through  9,  unless  explicitly  stated  otherwise: 

(1)  If  an  argument  to  a  function  has  an  invalid  value  (such  as  a  value  outside 
the  domain  of  the  function,  or  a  pointer  outside  the  address  space  of  the 
program,  or  a  NULL  pointer  when  that  is  not  explicitly  permitted),  the 
behavior  is  undefined. 

(2)  Any  function  may  also  be  implemented  as  a  macro  in  a  header.  Applica¬ 
tions  should  use  #undef  to  remove  any  macro  definition  and  ensure  that 
an  actual  function  is  referenced.  Applications  should  also  use  tundef 
prior  to  declaring  any  function  in  this  part  of  ISO/IEC  9945. 

(3)  Any  invocation  of  a  library  function  that  is  implemented  as  a  macro  shall 
expand  to  code  that  evaluates  each  of  its  arguments  only  once,  fully  pro¬ 
tected  by  parentheses  where  necessary,  so  it  is  generally  safe  to  use  arbi¬ 
trary  expressions  as  arguments. 

(4)  Provided  that  a  library  function  can  be  declared  without  reference  to  any 
type  defined  in  a  header,  it  is  also  permissible  to  declare  the  function, 
either  explicitly  or  implicitly,  and  use  it  without  including  its  associated 
header. 
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(5)  If  a  function  that  accepts  a  variable  number  of  arguments  is  not  declared 
(explicitly  or  by  including  its  associated  header),  the  behavior  is 
undefined. 


1.3.5  Other  Language-Related  Specifications 

This  part  of  ISO/IEC  9945  is  currently  specified  in  terms  of  the  language  defined 
by  the  C  Standard  {2}.  Bindings  to  other  programming  languages  are  being 
developed. 

If  conformance  to  this  part  of  ISO/IEC  9945  is  claimed  for  implementation  of  any 
programming  language,  the  implementation  of  that  language  shall  support  the 
use  of  external  symbols  distinct  to  at  least  31  bytes  in  length  in  the  source  pro¬ 
gram  text.  (That  is,  identifiers  that  differ  at  or  before  the  thirty-first  byte  shall  be 
distinct.)  If  a  national  or  international  standard  governing  a  language  defines  a 
maximum  length  that  is  less  than  this  value,  the  language-defined  maximum 
shall  be  supported.  External  symbols  that  differ  only  by  case  shall  be  distinct 
when  the  character  set  in  use  distinguishes  upper-  and  lowercase  characters  and 
the  language  permits  (or  requires)  upper-  and  lowercase  characters  to  be  distinct 
in  external  symbols. 

Subsequent  sections  of  this  part  of  ISO/IEC  9945  refer  only  to  the  C  Language. 


1.3  Conformance 


7 


1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


Section  2:  Terminology  and  General  Requirements 


2.1  Conventions 

This  part  of  ISO/IEC  9945  uses  the  following  typographic  conventions: 

(1)  The  italic  font  is  used  for: 

—  Cross  references  to  defined  terms  within  1.3,  2.2.1,  and  2.2.2;  symbolic 
parameters  that  are  generally  substituted  with  real  values  by  the 
application 

—  C  language  data  types  and  function  names  (except  in  function 
Synopsis  subclauses) 

—  Global  external  variable  names 

(2)  The  bold  font  is  used  with  a  word  in  all  capital  letters,  such  as 

PATH 

to  represent  an  environment  variable,  as  described  in  2.6.  It  is  also  used 
for  the  term  “NULL  pointer.” 

(3)  The  con st ant -width  (Courier)  font  is  used: 

—  For  C  language  data  types  and  function  names  within  function 
Synopsis  subclauses 

—  To  illustrate  examples  of  system  input  or  output  where  exact  usage  is 
depicted 

—  For  references  to  utility  names  and  C  language  headers 

(4)  Symbolic  constants  returned  by  many  functions  as  error  numbers  are 
represented  as: 

[ERRNO] 

See  2.4. 

(5)  Symbolic  constants  or  limits  defined  in  certain  headers  are  represented 
as: 


{LIMIT} 

See  2.8  and  2.9. 

In  some  cases  tabular  information  is  presented  “inline”;  in  others  it  is  presented 
in  a  separately  labeled  table.  This  arrangement  was  employed  purely  for  ease  of 
typesetting  and  there  is  no  normative  difference  between  these  two  cases. 
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31  The  conventions  listed  previously  are  for  ease  of  reading  only.  Editorial  incon-  | 

32  sistencies  in  the  use  of  typography  are  unintentional  and  have  no  normative 

33  meaning  in  this  part  of  ISO/IEC  9945. 

34  NOTEs  provided  as  parts  of  labeled  tables  and  figures  are  integral  parts  of  this  | 

35  part  of  ISO/IEC  9945  (normative).  Footnotes  and  notes  within  the  body  of  the  text  | 

36  are  for  information  only  (informative).  | 

37  Numerical  quantities  are  presented  in  international  style:  comma  is  used  as  a  | 

38  decimal  sign  and  units  are  from  the  International  System  (SI). 


39  2.2  Definitions 


40  2.2.1  Terminology 

41  For  the  purposes  of  this  part  of  ISO/IEC  9945,  the  following  definitions  apply: 

42  2.2.1. 1  conformance  document:  A  document  provided  by  an  implementor  that  | 

43  contains  implementation  details  as  described  in  1.3. 1.2. 

44  2.2.1.2  implementation  defined:  An  indication  that  the  implementation  shall  | 

45  define  and  document  the  requirements  for  correct  program  constructs  and  correct  | 

46  data  of  a  value  or  behavior. 


47  2.2. 1.3  may:  An  indication  of  an  optional  feature. 

48  With  respect  to  implementations,  the  word  may  is  to  be  interpreted  as  an  optional 

49  feature  that  is  not  required  in  this  part  of  ISO/IEC  9945,  but  can  be  provided, 

so  With  respect  to  Strictly  Conforming  POSIX.  1  Applications,  the  word  may  means 

5i  that  the  optional  feature  shall  not  be  used. 


52  2.2. 1.4  obsolescent:  An  indication  that  a  certain  feature  may  be  considered  for 

53  withdrawal  in  future  revisions  of  this  part  of  ISO/IEC  9945. 

54  Obsolescent  features  are  retained  in  this  version  because  of  their  widespread  use. 

55  Their  use  in  new  applications  is  discouraged. 


56  2.2. 1.5  shall:  An  indication  of  a  requirement  on  the  implementation  or  on 

57  Strictly  Conforming  POSIX.l  Applications,  where  appropriate. 

58  2.2. 1.6  should: 

59  (1)  With  respect  to  implementations,  an  indication  of  an  implementation 

60  recommendation,  but  not  a  requirement. 


61 

62 

63 


(2)  With  respect  to  applications,  an  indication  of  a  recommended  program-  | 
ming  practice  for  applications  and  a  requirement  for  Strictly  Conforming 
POSIX.l  Applications. 
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64  2.2. 1.7  supported:  A  condition  regarding  optional  functionality. 

65  Certain  functionality  in  this  part  of  ISO/IEC  9945  is  optional,  but  the  interfaces  to 

66  that  functionality  are  always  required.  If  the  functionality  is  supported ,  the 

67  interfaces  work  as  specified  by  this  part  of  ISO/IEC  9945  (except  that  they  do  not 

68  return  the  error  condition  indicated  for  the  unsupported  case).  If  the  functional- 

69  ity  is  not  supported ,  the  interface  shall  always  return  the  indication  specified  for 

70  this  situation. 

71  2.2. 1.8  system  documentation:  All  documentation  provided  with  an  imple-  | 

72  mentation,  except  the  conformance  document. 

73  Electronically  distributed  documents  for  an  implementation  are  considered  part  of  | 

74  the  system  documentation. 

75  2.2.1.9  undefined:  An  indication  that  this  part  of  ISO/IEC  9945  imposes  no  por-  | 

76  tability  requirements  on  an  application’s  use  of  an  indeterminate  value  or  its  | 

77  behavior  with  erroneous  program  constructs  or  erroneous  data. 

78  Implementations  (or  other  standards)  may  specify  the  result  of  using  that  value  or 

79  causing  that  behavior.  An  application  using  such  behaviors  is  using  extensions, 

so  as  defined  in  1.3. 2.3. 

81  2.2.1.10  unspecified:  An  indication  that  this  part  of  ISO/IEC  9945  imposes  no  | 

82  portability  requirements  on  applications  for  correct  program  constructs  or  correct  | 

83  data  regarding  a  value  or  behavior.  | 

84  Implementations  (or  other  standards)  may  specify  the  result  of  using  that  value  or 

85  causing  that  behavior.  An  application  requiring  a  specific  behavior,  rather  than 

86  tolerating  any  behavior  when  using  that  functionality,  is  using  extensions,  as 

87  defined  in  1.3.2. 3. 

88  2.2.2  General  Terms 

89  For  the  purposes  of  this  part  of  ISO/IEC  9945,  the  following  definitions  apply: 

90  2.2.2.1  absolute  pathname:  See  pathname  resolution  in  2.3.6. 

91  2.2.2.2  access  mode:  A  form  of  access  permitted  to  a  file. 

92  2.2.2.3  address  space:  The  memory  locations  that  can  be  referenced  by  a 

93  process. 

94  2.2.2.4  appropriate  privileges:  An  implementation-defined  means  of  associat- 

95  ing  privileges  with  a  process  with  regard  to  the  function  calls  and  function  call 

96  options  defined  in  this  part  of  ISO/IEC  9945  that  need  special  privileges. 

97  There  may  be  zero  or  more  such  means. 
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98  2.2.2.5  background  process:  A  process  that  is  a  member  of  a  background  pro-  | 

99  cess  group.  | 

100  2.2.2.6  background  process  group:  Any  process  group,  other  than  a  fore-  | 

101  ground  process  group,  that  is  a  member  of  a  session  that  has  established  a  con-  j 

102  nection  with  a  controlling  terminal.  | 

103  2.2.2.7  block  special  file:  A  file  that  refers  to  a  device. 

104  A  block  special  file  is  normally  distinguished  from  a  character  special  file  by  pro- 

105  viding  access  to  the  device  in  a  manner  such  that  the  hardware  characteristics  of 

106  the  device  are  not  visible. 

107  2.2.2.8  character:  A  sequence  of  one  or  more  bytes  representing  a  single 

108  graphic  symbol. 

109  NOTE:  This  term  corresponds  in  the  C  Standard  {2}  to  the  term  multibyte  character,  noting  that  a 

110  single-byte  character  is  a  special  case  of  multi  byte  character.  Unlike  the  usage  in  the  C  Standard 

111  {2},  character  here  has  no  necessary  relationship  with  storage  space,  and  byte  is  used  when  storage 

112  space  is  discussed. 

113  2.2.2.9  character  special  file:  A  file  that  refers  to  a  device. 

114  One  specific  type  of  character  special  file  is  a  terminal  device  file,  whose  access  is 

ns  defined  in  7.1.  Other  character  special  files  have  no  structure  defined  by  this  part 

116  of  ISO/IEC  9945,  and  their  use  is  unspecified  by  this  part  of  ISO/IEC  9945.  | 

117  2.2.2.10  child  process:  See  process  in  2.2.2.62. 

ns  2.2.2.11  clock  tick:  An  interval  of  time.  | 

119  A  number  of  these  occur  each  second.  Clock  ticks  are  one  of  the  units  that  may  be  | 

120  used  to  express  a  value  found  in  type  clock  _t.  | 

121  2.2.2.12  controlling  process:  The  session  leader  that  established  the  connec- 

122  tion  to  the  controlling  terminal. 

123  Should  the  terminal  subsequently  cease  to  be  a  controlling  terminal  for  this  ses- 

124  sion,  the  session  leader  shall  cease  to  be  the  controlling  process. 

125  2.2.2.13  controlling  terminal:  A  terminal  that  is  associated  with  a  session. 

126  Each  session  may  have  at  most  one  controlling  terminal  associated  with  it,  and  a 

127  controlling  terminal  is  associated  with  exactly  one  session.  Certain  input 

128  sequences  from  the  controlling  terminal  (see  7.1)  cause  signals  to  be  sent  to  all 

129  processes  in  the  process  group  associated  with  the  controlling  terminal. 

130  2.2.2.14  current  working  directory:  See  working  directory  in  2.2.2.89. 
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131  2.2.2.15  device:  A  computer  peripheral  or  an  object  that  appears  to  the  applica- 

132  tion  as  such. 

133  2.2.2.16  directory:  A  file  that  contains  directory  entries. 

134  No  two  directory  entries  in  the  same  directory  shall  have  the  same  name. 

135  2.2.2.17  directory  entry  [link]:  An  object  that  associates  a  filename  with  a  file. 

136  Several  directory  entries  can  associate  names  with  the  same  file. 

137  2.2.2.18  dot:  The  filename  consisting  of  a  single  dot  character  ( . ). 

138  See  pathname  resolution  in  2.3.6. 

139  2.2.2.19  dot-dot:  The  filename  consisting  solely  of  two  dot  characters  ( .  . ). 

140  See  pathname  resolution  in  2.3.6. 

141  2.2.2.20  effective  group  ID:  An  attribute  of  a  process  that  is  used  in  determin- 

142  ing  various  permissions,  including  file  access  permissions,  described  in  2.3.2. 

143  See  group  ID.  This  value  is  subject  to  change  during  the  process  lifetime,  as 

144  described  in  3.1.2  and  4.2.2. 

145  2.2.2.21  effective  user  ID:  An  attribute  of  a  process  that  is  used  in  determining 

146  various  permissions,  including  file  access  permissions. 

147  See  user  ID.  This  value  is  subject  to  change  during  the  process  lifetime,  as 

148  described  in  3.1.2  and  4.2.2. 

149  2.2.2.22  empty  directory:  A  directory  that  contains,  at  most,  directory  entries 

150  for  dot  and  dot-dot. 

151  2.2.2.23  empty  string  [null  string]:  A  character  array  whose  first  element  is  a 

152  null  character. 

153  2.2.2.24  Epoch:  The  time  0  hours,  0  minutes,  0  seconds,  January  1,  1970,  Coor- 

154  dinated  Universal  Time. 

155  See  seconds  since  the  Epoch . 

156  2.2.2.25  feature  test  macro:  A  #def  ined  symbol  used  to  determine  whether  a 

157  particular  set  of  features  will  be  included  from  a  header. 

158  See  2.7.1. 

159  2.2.2.26  FIFO  special  file  [FIFO]:  A  type  of  file  with  the  property  that  data  | 

160  written  to  such  a  file  is  read  on  a  first-in-first-out  basis. 
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161  Other  characteristics  of  FIFOs  are  described  in  5.3.1,  6.4.1,  6.4.2,  and  6.5.3. 

162  2.2.2.27  file:  An  object  that  can  be  written  to,  or  read  from,  or  both. 

163  A  file  has  certain  attributes,  including  access  permissions  and  type.  File  types 

164  include  regular  file,  character  special  file,  block  special  file,  FIFO  special  file,  and 

165  directory.  Other  types  of  files  may  be  defined  by  the  implementation. 

166  2.2.2.28  file  description:  See  open  file  description  in  2.2.2.51. 

167  2.2.2.29  file  descriptor:  A  per-process  unique,  nonnegative  integer  used  to 

168  identify  an  open  file  for  the  purpose  of  file  access. 

169  2.2.2.30  file  group  class:  The  property  of  a  file  indicating  access  permissions  | 

170  for  a  process  related  to  the  process’s  group  identification.  | 

ni  A  process  is  in  the  file  group  class  of  a  file  if  the  process  is  not  in  the  file  owner 

172  class  and  if  the  effective  group  ID  or  one  of  the  supplementary  group  IDs  of  the 

173  process  matches  the  group  ID  associated  with  the  file.  Other  members  of  the  class 

174  may  be  implementation  defined. 

175  2.2.2.31  file  mode:  An  object  containing  the  file  permission  bits  and  other 

176  characteristics  of  a  file,  as  described  in  5.6.1. 

177  2.2.2.32  filename:  A  name  consisting  of  1  to  {NAME_MAX}  bytes  used  to  name  a 

178  file. 

179  The  characters  composing  the  name  may  be  selected  from  the  set  of  all  character 

180  values  excluding  the  slash  character  and  the  null  character.  The  filenames  dot 

181  and  dot-dot  have  special  meaning;  see  pathname  resolution  in  2.3.6.  A  filename  is 

182  sometimes  referred  to  as  a  pathname  component. 

183  2.2.2.33  file  offset:  The  byte  position  in  the  file  where  the  next  I/O  operation 

184  begins. 

185  Each  open  file  description  associated  with  a  regular  file,  block  special  file,  or 

186  directory  has  a  file  offset.  A  character  special  file  that  does  not  refer  to  a  terminal 

187  device  may  have  a  file  offset.  There  is  no  file  offset  specified  for  a  pipe  or  FIFO. 

188  2.2.2.34  file  other  class:  The  property  of  a  file  indicating  access  permissions  for  | 

189  a  process  related  to  the  process’s  user  and  group  identification. 

190  A  process  is  in  the  file  other  class  of  a  file  if  the  process  is  not  in  the  file  owner 

191  class  or  file  group  class. 

192  2.2.2.35  file  owner  class:  The  property  of  a  file  indicating  access  permissions  | 

193  for  a  process  related  to  the  process’s  user  identification.  | 

194  A  process  is  in  the  file  owner  class  of  a  file  if  the  effective  user  ID  of  the  process 

195  matches  the  user  ID  of  the  file. 
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196  2.2.2.36  file  permission  bits:  Information  about  a  file  that  is  used,  along  with 

197  other  information,  to  determine  if  a  process  has  read,  write,  or  execute/search  per- 

198  mission  to  a  file. 

199  The  bits  are  divided  into  three  parts:  owner,  group,  and  other.  Each  part  is  used 

200  with  the  corresponding  file  class  of  processes.  These  bits  are  contained  in  the  file 

201  mode,  as  described  in  5.6.1.  The  detailed  usage  of  the  file  permission  bits  in 

202  access  decisions  is  described  in  file  access  permissions  in  2.3.2. 

203  2.2.2.37  file  serial  number:  A  per-file  system  unique  identifier  for  a  file. 

204  File  serial  numbers  are  unique  throughout  a  file  system. 

205  2.2.2.38  file  system:  A  collection  of  files  and  certain  of  their  attributes. 

206  It  provides  a  name  space  for  file  serial  numbers  referring  to  those  files. 

207  2.2.2.39  foreground  process:  A  process  that  is  a  member  of  a  foreground  pro-  | 

208  cess  group.  | 

209  2.2.2.40  foreground  process  group:  A  process  group  whose  member  processes  | 

210  have  certain  privileges,  denied  to  processes  in  background  process  groups,  when  | 

211  accessing  their  controlling  terminal.  | 

212  Each  session  that  has  established  a  connection  with  a  controlling  terminal  has 

213  exactly  one  process  group  of  the  session  as  the  foreground  process  group  of  that 

214  controlling  terminal.  See  7.1. 1.4. 

215  2.2.2.41  foreground  process  group  ID:  The  process  group  ID  of  the  foreground 

216  process  group. 

217  2.2.2.42  group  ID:  A  nonnegative  integer,  which  can  be  contained  in  an  object  of  | 

218  type  gidjt,  that  is  used  to  identify  a  group  of  system  users. 

219  Each  system  user  is  a  member  of  at  least  one  group.  When  the  identity  of  a  group  | 

220  is  associated  with  a  process,  a  group  ID  value  is  referred  to  as  a  real  group  ID,  an 

221  effective  group  ID,  one  of  the  (optional)  supplementary  group  IDs,  or  an  (optional) 

222  saved  set-group-ID. 

223  2.2.2.43  job  control:  A  facility  that  allows  users  to  selectively  stop  (suspend) 

224  the  execution  of  processes  and  continue  (resume)  their  execution  at  a  later  point. 

225  The  user  typically  employs  this  facility  via  the  interactive  interface  jointly  sup- 

226  plied  by  the  terminal  I/O  driver  and  a  command  interpreter.  Conforming  imple- 

227  mentations  may  optionally  support  job  control  facilities;  the  presence  of  this 

228  option  is  indicated  to  the  application  at  compile  time  or  run  time  by  the  definition 

229  of  the  {_POSIX_JOB_CONTROL}  symbol;  see  2.9. 

230  2.2.2.44  link:  See  directory  entry  in  2.2.2.17. 
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231  2.2.2.45  link  count:  The  number  of  directory  entries  that  refer  to  a  particular 

232  file. 

233  2.2.2.46  login:  The  unspecified  activity  by  which  a  user  gains  access  to  the  | 

234  system.  | 

235  Each  login  shall  be  associated  with  exactly  one  login  name.  | 

236  2.2.2.47  login  name:  A  user  name  that  is  associated  with  a  login.  | 

237  2.2.2.48  mode:  A  collection  of  attributes  that  specifies  a  file’s  type  and  its  access 

238  permissions. 

239  See  file  access  permissions  in  2.3.2. 

240  2.2.2.49  null  string:  See  empty  string  in  2.2.2.23. 

241  2.2.2.50  open  file:  A  file  that  is  currently  associated  with  a  file  descriptor. 

242  2.2.2.51  open  file  description:  A  record  of  how  a  process  or  group  of  processes 

243  are  accessing  a  file. 

244  Each  file  descriptor  shall  refer  to  exactly  one  open  file  description,  but  an  open  file 

245  description  may  be  referred  to  by  more  than  one  file  descriptor.  A  file  offset,  file 

246  status  (see  Table  6-5),  and  file  access  modes  (see  Table  6-6)  are  attributes  of  an 

247  open  file  description. 

248  2.2.2.52  orphaned  process  group:  A  process  group  in  which  the  parent  of 

249  every  member  is  either  itself  a  member  of  the  group  or  is  not  a  member  of  the 

250  group’s  session. 


251 

252 

253 

254 


2.2.2.53  parent  directory:  | 

(1)  When  discussing  a  given  directory,  the  directory  that  both  contains  a  | 
directory  entry  for  the  given  directory  and  is  represented  by  the  path-  | 
name  dot-dot  in  the  given  directory. 


255  (2)  When  discussing  other  types  of  files,  a  directory  containing  a  directory 

256  entry  for  the  file  under  discussion. 


257  This  concept  does  not  apply  to  dot  and  dot-dot. 


258  2.2.2.54  parent  process:  See  process  in  2.2.2.62. 

259  2.2.2.55  parent  process  ID:  An  attribute  of  a  new  process  after  it  is  created  by  | 

260  a  currently  active  process.  | 

261  The  parent  process  ID  of  a  process  is  the  process  ID  of  its  creator,  for  the  lifetime 

262  of  the  creator.  After  the  creator’s  lifetime  has  ended,  the  parent  process  ID  is  the 

263  process  ID  of  an  implementation-defined  system  process. 
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264  2.2.2.56  path  prefix:  A  pathname,  with  an  optional  ending  slash,  that  refers  to 

265  a  directory. 

266  2.2.2.57  pathname:  A  string  that  is  used  to  identify  a  file. 

267  A  pathname  consists  of,  at  most,  {PATH_MAX}  bytes,  including  the  terminating 

268  null  character.  It  has  an  optional  beginning  slash,  followed  by  zero  or  more 

269  filenames  separated  by  slashes.  If  the  pathname  refers  to  a  directory,  it  may  also 

270  have  one  or  more  trailing  slashes.  Multiple  successive  slashes  are  considered  to 

271  be  the  same  as  one  slash.  A  pathname  that  begins  with  two  successive  slashes 

272  may  be  interpreted  in  an  implementation-defined  manner,  although  more  than 

273  two  leading  slashes  shall  be  treated  as  a  single  slash.  The  interpretation  of  the 

274  pathname  is  described  in  2.3.6. 

275  2.2.2.58  pathname  component:  See  filename  in  2.2.2.32. 

276  2.2.2.59  pipe:  An  object  accessed  by  one  of  the  pair  of  file  descriptors  created  by 

277  the  pipe  ()  function. 

278  Once  created,  the  file  descriptors  can  be  used  to  manipulate  it,  and  it  behaves 

279  identically  to  a  FIFO  special  file  when  accessed  in  this  way.  It  has  no  name  in  the 

280  file  hierarchy. 

281  2.2.2.60  portable  filename  character  set:  The  set  of  characters  from  which  | 

282  portable  filenames  are  constructed.  I 

283  For  a  filename  to  be  portable  across  conforming  implementations  of  this  part  of 

284  ISO/IEC  9945,  it  shall  consist  only  of  the  following  characters: 

285  ABCDEFGHIJKLMNOPQRSTUVWXYZ 

286  abcdefghijklmnopqrstuvwxyz 

287  0  1  2  3  4  5  6  7  8  9. 

288  The  last  three  characters  are  the  period,  underscore,  and  hyphen  characters, 

289  respectively.  The  hyphen  shall  not  be  used  as  the  first  character  of  a  portable 

290  filename.  Upper-  and  lowercase  letters  shall  retain  their  unique  identities 

291  between  conforming  implementations.  In  the  case  of  a  portable  pathname,  the 

292  slash  character  may  also  be  used. 

293  2.2.2.61  privilege:  See  appropriate  privileges  in  2. 2. 2.4. 

294  2.2.2.62  process:  An  address  space  and  single  thread  of  control  that  executes 

295  within  that  address  space,  and  its  required  system  resources. 

296  A  process  is  created  by  another  process  issuing  the  fork( )  function.  The  process 

297  that  issues  fork()  is  known  as  the  parent  process,  and  the  new  process  created  by 

298  the  forkO  is  known  as  the  child  process. 

299  2.2.2.63  process  group:  A  collection  of  processes  that  permits  the  signaling  of  | 

300  related  processes. 
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301  Each  process  in  the  system  is  a  member  of  a  process  group  that  is  identified  by  a 

302  process  group  ID.  A  newly  created  process  joins  the  process  group  of  its  creator. 

303  2.2.2.64  process  group  ID:  The  unique  identifier  representing  a  process  group  | 

304  during  its  lifetime.  | 

305  A  process  group  ID  is  a  positive  integer  that  can  be  contained  in  a  pidjt.  It  shall  | 

306  not  be  reused  by  the  system  until  the  process  group  lifetime  ends. 

307  2.2.2.65  process  group  leader:  A  process  whose  process  ID  is  the  same  as  its 

308  process  group  ID. 

309  2.2.2.66  process  group  lifetime:  A  period  of  time  that  begins  when  a  process 

310  group  is  created  and  ends  when  the  last  remaining  process  in  the  group  leaves  the 

311  group,  due  either  to  the  end  of  the  last  process’s  process  lifetime  or  to  the  last  | 

312  remaining  process  calling  the  setsidi )  or  setpgidO  functions.  | 

313  2.2.2.67  process  ID:  The  unique  identifier  representing  a  process.  | 

314  A  process  ID  is  a  positive  integer  that  can  be  contained  in  a  pidj.  A  process  ID  | 

315  shall  not  be  reused  by  the  system  until  the  process  lifetime  ends.  In  addition,  if  | 

316  there  exists  a  process  group  whose  process  group  ID  is  equal  to  that  process  ID, 

317  the  process  ID  shall  not  be  reused  by  the  system  until  the  process  group  lifetime 

318  ends.  A  process  that  is  not  a  system  process  shall  not  have  a  process  ID  of  1. 

319  2.2.2.68  process  lifetime:  The  period  of  time  that  begins  when  a  process  is  | 

320  created  and  ends  when  its  process  ID  is  returned  to  the  system. 

321  After  a  process  is  created  with  a  fork{)  function,  it  is  considered  active.  Its  thread 

322  of  control  and  address  space  exist  until  it  terminates.  It  then  enters  an  inactive 

323  state  where  certain  resources  may  be  returned  to  the  system,  although  some 

324  resources,  such  as  the  process  ID,  are  still  in  use.  When  another  process  executes 

325  a  wait ()  or  waitpid ()  function  for  an  inactive  process,  the  remaining  resources  are 

326  returned  to  the  system.  The  last  resource  to  be  returned  to  the  system  is  the  pro- 

327  cess  ID.  At  this  time,  the  lifetime  of  the  process  ends. 

328  2.2.2.69  read-only  file  system:  A  file  system  that  has  implementation-defined 

329  characteristics  restricting  modifications. 

330  2.2.2.70  real  group  ID:  The  attribute  of  a  process  that,  at  the  time  of  process 

331  creation,  identifies  the  group  of  the  user  who  created  the  process. 

332  See  group  ID  in  2.2.2.42.  This  value  is  subject  to  change  during  the  process  life- 

333  time,  as  described  in  4.2.2. 

334  2.2.2.71  real  user  ID:  The  attribute  of  a  process  that,  at  the  time  of  process 

335  creation,  identifies  the  user  who  created  the  process. 

336  See  user  ID  in  2.2.2.87.  This  value  is  subject  to  change  during  the  process  life- 

337  time,  as  described  in  4.2.2. 
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338  2.2.2.72  regular  file:  A  file  that  is  a  randomly  accessible  sequence  of  bytes,  with 

339  no  further  structure  imposed  by  the  system. 

340  2.2.2.73  relative  pathname:  See  pathname  resolution  in  2.3.6. 

341  2.2.2.74  root  directory:  A  directory,  associated  with  a  process,  that  is  used  in 

342  pathname  resolution  for  pathnames  that  begin  with  a  slash. 

343  2.2.2.75  saved  set-group-ID:  An  attribute  of  a  process  that  allows  some  flexibil- 

344  ity  in  the  assignment  of  the  effective  group  ID  attribute,  when  the  saved  set-user- 

345  ID  option  is  implemented,  as  described  in  3.1.2  and  4.2.2. 

346  2.2.2.76  saved  set-user-ID:  An  attribute  of  a  process  that  allows  some  flexibil- 

347  ity  in  the  assignment  of  the  effective  user  ID  attribute,  when  the  saved  set-user-ID 

348  option  is  implemented,  as  described  in  3.1.2  and  4.2.2. 

349  2.2.2.77  seconds  since  the  Epoch:  A  value  to  be  interpreted  as  the  number  of 

350  seconds  between  a  specified  time  and  the  Epoch. 

351  A  Coordinated  Universal  Time  name  (specified  in  terms  of  seconds  ( tm_sec ), 

352  minutes  ( tmjnin ),  hours  ( tmjiour ),  days  since  January  1  of  the  year  ( tmjyday ), 

353  and  calendar  year  minus  1900  ( tmjyear )  is  related  to  a  time  represented  as 

354  seconds  since  the  Epoch,  according  to  the  expression  below. 

355  If  the  year  <  1970  or  the  value  is  negative,  the  relationship  is  undefined.  If  the 

356  year  >  1970  and  the  value  is  nonnegative,  the  value  is  related  to  a  Coordinated 

357  Universal  Time  name  according  to  the  expression: 

358  tm_sec  +  tm_min*6  0  +  tmjiour* 3  600  +  tm_yday*8 6400  + 

359  (tmjyear- 70)*31 536  000  +  (( tmjyear-69)/4:)*86  400 

360  2.2.2.78  session:  A  collection  of  process  groups  established  for  job  control  | 

361  purposes.  | 

362  Each  process  group  is  a  member  of  a  session.  A  process  is  considered  to  be  a 

363  member  of  the  session  of  which  its  process  group  is  a  member.  A  newly  created 

364  process  joins  the  session  of  its  creator.  A  process  can  alter  its  session  membership 

365  (see  4.3.2).  Implementations  that  support  the  setpgidi)  function  (see  4.3.3)  can 

366  have  multiple  process  groups  in  the  same  session. 

367  2.2.2.79  session  leader:  A  process  that  has  created  a  session  (see  4.3.2). 

368  2.2.2.80  session  lifetime:  The  period  between  when  a  session  is  created  and  the 

369  end  of  the  lifetime  of  all  the  process  groups  that  remain  as  members  of  the 

370  session. 

371  2.2.2.81  signal:  A  mechanism  by  which  a  process  may  be  notified  of,  or  affected 

372  by,  an  event  occurring  in  the  system. 
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373  Examples  of  such  events  include  hardware  exceptions  and  specific  actions  by 

374  processes.  The  term  signal  is  also  used  to  refer  to  the  event  itself. 

375  2.2.2.82  slash:  The  literal  character 

376  This  character  is  also  known  as  solidus  in  ISO  8859-1  {B34}. 

377  2.2.2.83  supplementary  group  ID:  An  attribute  of  a  process  used  in  determin-  | 

378  ing  file  access  permissions.  | 

379  A  process  has  up  to  {NGROUPS_MAX}  supplementary  group  IDs  in  addition  to  the 

380  effective  group  ID.  The  supplementary  group  IDs  of  a  process  are  set  to  the  sup- 

381  plementary  group  IDs  of  the  parent  process  when  the  process  is  created.  Whether 

382  a  process’s  effective  group  ID  is  included  in  or  omitted  from  its  list  of  supplemen- 

383  tary  group  IDs  is  unspecified. 

384  2.2.2.84  system:  An  implementation  of  this  part  of  ISO/IEC  9945. 

385  2.2.2.85  system  process:  An  object,  other  than  a  process  executing  an  applica- 

386  tion,  that  is  defined  by  the  system  and  has  a  process  ID. 

387  2.2.2.86  terminal  [terminal  device]:  A  character  special  file  that  obeys  the 

388  specifications  of  7. 1 . 

389  2.2.2.87  user  ID:  A  nonnegative  integer,  which  can  be  contained  in  an  object  of  | 

390  type  uidjt ,  that  is  used  to  identify  a  system  user. 

391  When  the  identity  of  a  user  is  associated  with  a  process,  a  user  ID  value  is 

392  referred  to  as  a  real  user  ID,  an  effective  user  ID,  or  an  (optional)  saved 

393  set-user-ID. 

394  2.2.2.88  user  name:  A  string  that  is  used  to  identify  a  user,  as  described  in  9.1. 

395  2.2.2.89  working  directory  [current  working  directory]:  A  directory,  asso- 

396  dated  with  a  process,  that  is  used  in  pathname  resolution  for  pathnames  that  do 

397  not  begin  with  a  slash. 

398  2.2.3  Abbreviations  | 

399  For  the  purposes  of  this  part  of  ISO/IEC  9945,  the  following  abbreviations  apply:  | 

400  2.2.3.1  C  Standard:  ISO/IEC  9899,  Information  technology — Programming  \ 

401  languages — C  {2}.  | 

402  2.2.3.2  IRV:  The  International  Reference  Version  coded  character  set  described  | 

403  in  ISO/IEC  646  {1}.  | 
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2.3  General  Concepts 

2.3.1  extended  security  controls:  The  access  control  (see  file  access  permis¬ 
sions)  and  privilege  (see  appropriate  privileges  in  2.2. 2.4)  mechanisms  have  been 
defined  to  allow  implementation-defined  extended  security  controls.  These  permit 
an  implementation  to  provide  security  mechanisms  to  implement  different  secu¬ 
rity  policies  than  described  in  this  part  of  ISO/IEC  9945.  These  mechanisms  shall 
not  alter  or  override  the  defined  semantics  of  any  of  the  functions  in  this  part  of 
ISO/IEC  9945. 

2.3.2  file  access  permissions:  The  standard  file  access  control  mechanism  uses 
the  file  permission  bits,  as  described  below.  These  bits  are  set  at  file  creation  by 
open (),  creat(),  mkdir(),  and  mkfifoO  and  are  changed  by  chmod().  These  bits  are 
read  by  stat( )  or  fstat( ). 

Implementations  may  provide  additional  or  alternate  file  access  control  mechan¬ 
isms,  or  both.  An  additional  access  control  mechanism  shall  only  further  restrict 
the  access  permissions  defined  by  the  file  permission  bits.  An  alternate  access 
control  mechanism  shall: 

(1)  Specify  file  permission  bits  for  the  file  owner  class,  file  group  class,  and 
file  other  class  of  the  file,  corresponding  to  the  access  permissions,  to  be 
returned  by  stat( )  or  fstati). 

(2)  Be  enabled  only  by  explicit  user  action,  on  a  per-file  basis  by  the  file 
owner  or  a  user  with  the  appropriate  privilege. 

(3)  Be  disabled  for  a  file  after  the  file  permission  bits  are  changed  for  that 
file  with  chmod().  The  disabling  of  the  alternate  mechanism  need  not 
disable  any  additional  mechanisms  defined  by  an  implementation. 

Whenever  a  process  requests  file  access  permission  for  read,  write,  or 
execute/search,  if  no  additional  mechanism  denies  access,  access  is  determined  as 
follows: 

(1)  If  a  process  has  the  appropriate  privilege: 

(a)  If  read,  write,  or  directory  search  permission  is  requested,  access  is 
granted. 

(b)  If  execute  permission  is  requested,  access  is  granted  if  execute  per¬ 
mission  is  granted  to  at  least  one  user  by  the  file  permission  bits  or 
by  an  alternate  access  control  mechanism;  otherwise,  access  is 
denied. 

(2)  Otherwise: 

(a)  The  file  permission  bits  of  a  file  contain  read,  write,  and 
execute/search  permissions  for  the  file  owner  class,  file  group  class, 
and  file  other  class. 

(b)  Access  is  granted  if  an  alternate  access  control  mechanism  is  not  | 
enabled  and  the  requested  access  permission  bit  is  set  for  the  class  | 
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(file  owner  class,  file  group  class,  or  file  other  class)  to  which  the 
process  belongs,  or  if  an  alternate  access  control  mechanism  is  | 
enabled  and  it  allows  the  requested  access;  otherwise,  access  is 
denied. 

2.3.3  file  hierarchy:  Files  in  the  system  are  organized  in  a  hierarchical  struc¬ 
ture  in  which  all  of  the  nonterminal  nodes  are  directories  and  all  of  the  terminal 
nodes  are  any  other  type  of  file.  Because  multiple  directory  entries  may  refer  to 
the  same  file,  the  hierarchy  is  properly  described  as  a  “directed  graph.” 

2.3.4  filename  portability:  Filenames  should  be  constructed  from  the  portable 
filename  character  set  because  the  use  of  other  characters  can  be  confusing  or 
ambiguous  in  certain  contexts. 

2.3.5  file  times  update:  Each  file  has  three  distinct  associated  time  values:  | 
stjatime,  stjntime,  and  st_ctime.  The  st_atime  field  is  associated  with  the  times  | 
that  the  file  data  is  accessed;  stjntime  is  associated  with  the  times  that  the  file  | 
data  is  modified;  and  stjctime  is  associated  with  the  times  that  file  status  is  | 
changed.  These  values  are  returned  in  the  file  characteristics  structure,  as  | 
described  in  5.6.1. 

Any  function  in  this  part  of  ISO/IEC  9945  that  is  required  to  read  or  write  file  data  | 
or  change  the  file  status  indicates  which  of  the  appropriate  time-related  fields  are  | 
to  be  “marked  for  update.”  If  an  implementation  of  such  a  function  marks  for  | 
update  a  time-related  field  not  specified  by  this  part  of  ISO/IEC  9945,  this  shall  be  | 
documented,  except  that  any  changes  caused  by  pathname  resolution  need  not  be  | 
documented.  For  the  other  functions  in  this  part  of  ISO/IEC  9945  (those  that  are 
not  explicitly  required  to  read  or  write  file  data  or  change  file  status,  but  that  in  | 
some  implementations  happen  to  do  so),  the  effect  is  unspecified.  | 

An  implementation  may  update  fields  that  are  marked  for  update  immediately,  or 
it  may  update  such  fields  periodically.  When  the  fields  are  updated,  they  are  set 
to  the  current  time  and  the  update  marks  are  cleared.  All  fields  that  are  marked 
for  update  shall  be  updated  when  the  file  is  no  longer  open  by  any  process,  or 
when  a  stat{ )  or  fstat( )  is  performed  on  the  file.  Other  times  at  which  updates  are 
done  are  unspecified.  Updates  are  not  done  for  files  on  read-only  file  systems. 

2.3.6  pathname  resolution:  Pathname  resolution  is  performed  for  a  process  to 
resolve  a  pathname  to  a  particular  file  in  a  file  hierarchy.  There  may  be  multiple 
pathnames  that  resolve  to  the  same  file. 

Each  filename  in  the  pathname  is  located  in  the  directory  specified  by  its  prede¬ 
cessor  (for  example,  in  the  pathname  fragment  “a/b”,  file  “b”  is  located  in  direc¬ 
tory  “a”).  Pathname  resolution  fails  if  this  cannot  be  accomplished.  If  the  path¬ 
name  begins  with  a  slash,  the  predecessor  of  the  first  filename  in  the  pathname  is 
taken  to  be  the  root  directory  of  the  process  (such  pathnames  are  referred  to  as 
absolute  pathnames).  If  the  pathname  does  not  begin  with  a  slash,  the  predeces¬ 
sor  of  the  first  filename  of  the  pathname  is  taken  to  be  the  current  working  direc¬ 
tory  of  the  process  (such  pathnames  are  referred  to  as  “relative  pathnames”). 

The  interpretation  of  a  pathname  component  is  dependent  on  the  values  of 
{NAME_MAX}  and  {_POSIX_NO_TRUNC}  associated  with  the  path  prefix  of  that 
component.  If  any  pathname  component  is  longer  than  {NAME_MAX},  and 
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{_POSIX_NO_TRUNC}  is  in  effect  for  the  path  prefix  of  that  component  (see  5.7.1), 
the  implementation  shall  consider  this  an  error  condition.  Otherwise,  the  imple¬ 
mentation  shall  use  the  first  {NAME_MAX}  bytes  of  the  pathname  component. 

The  special  filename,  dot,  refers  to  the  directory  specified  by  its  predecessor.  The 
special  filename,  dot-dot,  refers  to  the  parent  directory  of  its  predecessor  direc¬ 
tory.  As  a  special  case,  in  the  root  directory,  dot-dot  may  refer  to  the  root  direc¬ 
tory  itself. 

A  pathname  consisting  of  a  single  slash  resolves  to  the  root  directory  of  the  pro¬ 
cess.  A  null  pathname  is  invalid. 


2.4  Error  Numbers 

Most  functions  provide  an  error  number  in  the  external  variable  errno,  which  is 
defined  as: 

extern  int  errno; 

The  value  of  this  variable  shall  be  defined  only  after  a  call  to  a  function  for  which 
it  is  explicitly  stated  to  be  set  and  until  it  is  changed  by  the  next  function  call. 
The  variable  errno  should  only  be  examined  when  it  is  indicated  to  be  valid  by  a 
function’s  return  value.  No  function  defined  in  this  part  of  ISO/IEC  9945  sets 
errno  to  zero  to  indicate  an  error. 

If  more  than  one  error  occurs  in  processing  a  function  call,  this  part  of 
ISO/IEC  9945  does  not  define  in  what  order  the  errors  are  detected;  therefore,  any 
one  of  the  possible  errors  may  be  returned. 

Implementations  may  support  additional  errors  not  included  in  this  clause,  may  | 
generate  errors  included  in  this  clause  under  circumstances  other  than  those  | 
described  in  this  clause,  or  may  contain  extensions  or  limitations  that  prevent 
some  errors  from  occurring.  The  Errors  subclause  in  each  function  description 
specifies  which  error  conditions  shall  be  detected  by  all  implementations  and  | 
which  may  be  optionally  detected  by  an  implementation.  Each  implementation  | 
shall  document,  in  the  conformance  document,  situations  in  which  each  of  the  | 
optional  conditions  are  detected.  If  no  error  condition  is  detected,  the  action 
requested  shall  be  successful.  Implementations  may  contain  extensions  or  limita-  | 
tions  that  prevent  some  specified  errors  from  occurring. 

Implementations  may  generate  error  numbers  listed  in  this  clause  under  cir-  | 
cumstances  other  than  those  described,  if  and  only  if  all  those  error  conditions  can  | 
always  be  treated  identically  to  the  error  conditions  as  described  in  this  part  of  | 
ISO/IEC  9945.  Implementations  may  support  additional  errors  not  listed  in  this  | 
clause,  but  shall  not  generate  a  different  error  number  from  one  required  by  this  | 
part  of  ISO/IEC  9945  for  an  error  condition  described  in  this  part  of  ISO/IEC  9945. 

The  following  symbolic  names  identify  the  possible  error  numbers,  in  the  context 
of  functions  specifically  defined  in  this  part  of  ISO/IEC  9945;  these  general  descrip¬ 
tions  are  more  precisely  defined  in  the  Errors  subclauses  of  functions  that  return 
them.  Only  these  symbolic  names  should  be  used  in  programs,  since  the  actual 
value  of  an  error  number  is  unspecified.  All  values  listed  in  this  clause  shall  be  | 
unique.  The  values  for  these  names  shall  be  found  in  the  header  <errno.h>. 
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The  actual  values  are  unspecified  by  this  part  of  ISO/IEC  9945. 
[E2BIG]  Arg  list  too  long 


[EACCES] 

The  sum  of  the  number  of  bytes  used  by  the  new  process  image’s 
argument  list  and  environment  list  was  greater  than  the  system- 
imposed  limit  of  {ARG_MAX}  bytes. 

Permission  denied 

An  attempt  was  made  to  access  a  file  in  a  way  forbidden  by  its  file 
access  permissions. 

[EAGAIN] 

Resource  temporarily  unavailable 

This  is  a  temporary  condition,  and  later  calls  to  the  same  routine 
may  complete  normally. 

[EBADF] 

Bad  file  descriptor 

A  file  descriptor  argument  was  out  of  range,  referred  to  no  open 
file,  or  a  read  (write)  request  was  made  to  a  file  that  was  only 
open  for  writing  (reading). 

[EBUSY] 

Resource  busy 

An  attempt  was  made  to  use  a  system  resource  that  was  not 
available  at  the  time  because  it  was  being  used  by  a  process  in  a 
manner  that  would  have  conflicted  with  the  request  being  made 
by  this  process. 

[ECHILD] 

No  child  processes 

A  wait()  or  waitpidi)  function  was  executed  by  a  process  that  had 

no  existing  or  unwaited-for  child  processes. 

[EDEADLK]  Resource  deadlock  avoided 

An  attempt  was  made  to  lock  a  system  resource  that  would  have 


[EDOM] 

resulted  in  a  deadlock  situation. 

Domain  error 

Defined  in  the  C  Standard  {2};  an  input  argument  was  outside  the 
defined  domain  of  the  mathematical  function. 

[EEXIST] 

File  exists 

An  existing  file  was  specified  in  an  inappropriate  context;  for 
instance,  as  the  new  link  name  in  a  link()  function. 

[EFAULT] 

Bad  address 

The  system  detected  an  invalid  address  in  attempting  to  use  an 
argument  of  a  call.  The  reliable  detection  of  this  error  is  imple¬ 
mentation  defined;  however,  implementations  that  do  detect  this 
condition  shall  use  this  value. 

[EFBIG] 

File  too  large 

The  size  of  a  file  would  exceed  an  implementation- defined  max¬ 
imum  file  size. 

[EINTR] 

Interrupted  function  call 

An  asynchronous  signal  (such  as  SIGINT  or  SIGQUIT;  see  the 
description  of  header  <signal.h>  in  3.3.1)  was  caught  by  the 
process  during  the  execution  of  an  interruptible  function.  If  the 
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[EINVAL] 

signal  handler  performs  a  normal  return,  the  interrupted  func¬ 
tion  call  may  return  this  error  condition. 

Invalid  argument 

Some  invalid  argument  was  supplied.  [For  example,  specifying 
an  undefined  signal  to  a  signali)  or  kill{)  function]. 

[EIOl 

Input/output  error 

Some  physical  input  or  output  error  occurred.  This  error  may  be 
reported  on  a  subsequent  operation  on  the  same  file  descriptor. 
Any  other  error-causing  operation  on  the  same  file  descriptor  may 
cause  the  [EIO]  error  indication  to  be  lost. 

[EISDIR] 

Is  a  directory 

An  attempt  was  made  to  open  a  directory  with  write  mode 
specified. 

[EMFILE] 

Too  many  open  files 

An  attempt  was  made  to  open  more  than  the  maximum  number  of 
{OPEN_MAX}  file  descriptors  allowed  in  this  process. 

[EMLINK] 

Too  many  links 

An  attempt  was  made  to  have  the  link  count  of  a  single  file  exceed 

{LINK_MAX}. 

[ENAMETOOLONG]  Filename  too  long 


[ENFILE] 

The  size  of  a  pathname  string  exceeded  [PATH_MAX],  or  a  path¬ 
name  component  was  longer  than  {NAME_MAX}  and 
[_POSIX_NO_TRUNC]  was  in  effect  for  that  file. 

Too  many  open  files  in  system 

Too  many  files  are  currently  open  in  the  system.  The  system 
reached  its  predefined  limit  for  simultaneously  open  files  and 
temporarily  could  not  accept  requests  to  open  another  one. 

[ENODEV] 

No  such  device 

An  attempt  was  made  to  apply  an  inappropriate  function  to  a  dev¬ 
ice;  for  example,  trying  to  read  a  write-only  device  such  as  a 
printer. 

[ENOENT] 

No  such  file  or  directory 

A  component  of  a  specified  pathname  did  not  exist,  or  the  path- 

name  was  an  empty  string. 

[ENOEXEC]  Exec  format  error 

A  request  was  made  to  execute  a  file  that,  although  it  had  the 


[ENOLCK] 

appropriate  permissions,  was  not  in  the  format  required  by  the 
implementation  for  executable  files. 

No  locks  available 

A  system-imposed  limit  on  the  number  of  simultaneous  file  and 
record  locks  was  reached,  and  no  more  were  available  at  that 
time. 

[ENOMEM] 

Not  enough  space 

The  new  process  image  required  more  memory  than  was  allowed 
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[ENOSPC] 

by  the  hardware  or  by  system-imposed  memory  management 
constraints. 

No  space  left  on  device 

During  a  write ()  function  on  a  regular  file,  or  when  extending  a 
directory,  there  was  no  free  space  left  on  the  device. 

[ENOSYS] 

Function  not  implemented 

An  attempt  was  made  to  use  a  function  that  is  not  available  in 
this  implementation. 

[ENOTDIR] 

Not  a  directory 

A  component  of  the  specified  pathname  existed,  but  it  was  not  a 

directory,  when  a  directory  was  expected. 
[ENOTEMPTY]  Directory  not  empty 


[ENOTTY1 

A  directory  with  entries  other  than  dot  and  dot-dot  was  supplied 
when  an  empty  directory  was  expected. 

Inappropriate  I/O  control  operation 

A  control  function  was  attempted  for  a  file  or  a  special  file  for 
which  the  operation  was  inappropriate. 

[ENXIOl 

No  such  device  or  address 

Input  or  output  on  a  special  file  referred  to  a  device  that  did  not 
exist,  or  made  a  request  beyond  the  limits  of  the  device.  This 
error  may  also  occur  when,  for  example,  a  tape  drive  is  not  online 
or  a  disk  pack  is  not  loaded  on  a  drive. 

[EPERM] 

Operation  not  permitted 

An  attempt  was  made  to  perform  an  operation  limited  to 
processes  with  appropriate  privileges  or  to  the  owner  of  a  file  or 
other  resource. 

[EPIPE] 

Broken  pipe 

A  write  was  attempted  on  a  pipe  or  FIFO  for  which  there  was  no 
process  to  read  the  data. 

[ERANGE] 

Result  too  large 

Defined  in  the  C  Standard  {2};  the  result  of  the  function  was  too 
large  to  fit  in  the  available  space. 

[EROFS] 

Read-only  file  system 

An  attempt  was  made  to  modify  a  file  or  directory  on  a  file  system 
that  was  read-only  at  that  time. 

[ESPIPE] 

Invalid  seek 

An  lseek{ )  function  was  issued  on  a  pipe  or  FIFO. 

[ESRCH1 

No  such  process 

No  process  could  be  found  corresponding  to  that  specified  by  the 
given  process  ID. 

[EXDEV] 

Improper  link 

A  link  to  a  file  on  another  file  system  was  attempted. 
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663  2.5  Primitive  System  Data  Types 

664  Some  data  types  used  by  the  various  system  functions  are  not  defined  as  part  of 

665  this  part  of  ISO/IEC  9945,  but  are  defined  by  the  implementation.  These  types  are 

666  then  defined  in  the  header  <sys/types .  h>,  which  contains  definitions  for  at 

667  least  the  types  shown  in  Table  2-1. 


668  Table  2-1  -  Primitive  System  Data  Types 

669  _ 


670 

671 

Defined 

Type 

Description 

672 

devjt 

Used  for  device  numbers. 

673 

gid_t 

Used  for  group  IDs. 

674 

inojt 

Used  for  file  serial  numbers. 

675 

modejt 

Used  for  some  file  attributes,  for  example  file  type,  file  access  permissions. 

676 

nlink  t 

Used  for  link  counts. 

677 

offj 

Used  for  file  sizes. 

678 

pid_t 

Used  for  process  IDs  and  process  group  IDs. 

679 

sizejt 

As  defined  in  the  C  Standard  {2}. 

680 

ssizejt 

Used  by  functions  that  return  a  count  of  bytes  (memory  space)  or  an  error  indication. 

681 

682 

uid_t 

Used  for  user  IDs. 

683  All  of  the  types  listed  in  Table  2-1  shall  be  arithmetic  types;  pid_t,  ssize_t,  and 

684  offjt  shall  be  signed  arithmetic  types.  The  type  ssizejt  shall  be  capable  of  storing 

685  values  in  the  range  from  -1  to  {SSIZE_MAX},  inclusive.  The  types  sizejt  and 

686  ssizejt  shall  also  be  defined  in  the  header  <unistd .  h>. 

687  Additional  unspecified  type  symbols  ending  in  J  may  be  defined  in  any  header 

688  specified  by  POSIX.l.  The  visibility  of  such  symbols  need  not  be  controlled  by  any 

689  feature  test  macro  other  than  _POSIX_SOURCE. 


690  2.6  Environment  Description 

691  An  array  of  strings  called  the  environment  is  made  available  when  a  process 

692  begins.  This  array  is  pointed  to  by  the  external  variable  environ ,  which  is  defined 

693  as: 

694  extern  char  **environ; 

695  These  strings  have  the  form  “name = value” \  names  shall  not  contain  the  character 

696  '  =' .  There  is  no  meaning  associated  with  the  order  of  the  strings  in  the  environ  - 

697  ment.  If  more  than  one  string  in  a  process’s  environment  has  the  same  name ,  the 

698  consequences  are  undefined.  The  following  names  may  be  defined  and  have  the 

699  indicated  meaning  if  they  are  defined: 

700  HOME  The  name  of  the  user’s  initial  working  directory  from  the 

701  user  database  (see  the  description  of  the  header  <pwd .  h> 

702  in  9.2.2). 
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LC_ALL 

LC_C  OLLATE 
LC_CTYPE 
LC_MONETARY 

LC_NUMERIC 

LC_TIME 

LOGNAME 


PATH 


TERM 
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The  name  of  the  locale  to  use  for  locale  categories  when  | 
both  LC_ALL  and  the  corresponding  environment  variable  | 
(beginning  with  “LC_”)  do  not  specify  a  locale. 

The  name  of  the  locale  to  be  used  to  override  any  values  | 
for  locale  categories  specified  by  the  setting  of  LANG  or  j 
any  environment  variables  beginning  with  “LC_”.  | 

The  name  of  the  locale  for  collation  information. 

The  name  of  the  locale  for  character  classification. 

The  name  of  the  locale  containing  monetary-related 
numeric  editing  information. 

The  name  of  the  locale  containing  numeric  editing  (i.e., 
radix  character)  information. 

The  name  of  the  locale  for  date/time  formatting 
information. 

The  login  name  associated  with  the  current  process.  The  | 
value  shall  be  composed  of  characters  from  the  portable  | 
filename  character  set.  | 

NOTE:  An  application  that  requires,  or  an  installation  that  actually 
uses,  characters  outside  the  portable  filename  character  set  would  not 
strictly  conform  to  this  part  of  ISO/IEC  9945.  However,  it  is  reasonable 
to  expect  that  such  characters  would  be  used  in  many  countries  (recog¬ 
nizing  the  reduced  level  of  interchange  implied  by  this),  and  applica¬ 
tions  or  installations  should  permit  such  usage  where  possible.  No 
error  is  defined  by  this  part  of  ISO/IEC  9945  for  violation  of  this 
condition. 

The  sequence  of  path  prefixes  that  certain  functions  apply 
in  searching  for  an  executable  file  known  only  by  a 
filename  (a  pathname  that  does  not  contain  a  slash).  The 
prefixes  are  separated  by  a  colon  ( : ).  When  a  nonzero- 
length  prefix  is  applied  to  this  filename,  a  slash  is 
inserted  between  the  prefix  and  the  filename.  A  zero- 
length  prefix  is  a  special  prefix  that  indicates  the  current 
working  directory.  It  appears  as  two  adjacent  colons  ( :  : ), 
as  an  initial  colon  preceding  the  rest  of  the  list,  or  as  a 
trailing  colon  following  the  rest  of  the  list.  The  list  is 
searched  from  beginning  to  end  until  an  executable  pro¬ 
gram  by  the  specified  name  is  found.  If  the  pathname 
being  sought  contains  a  slash,  the  search  through  the 
path  prefixes  is  not  performed. 

The  terminal  type  for  which  output  is  to  be  prepared. 
This  information  is  used  by  commands  and  application 
programs  wishing  to  exploit  special  capabilities  specific  to 
a  terminal. 
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TZ  Time  zone  information.  The  format  of  this  string  is 

defined  in  8.1.1. 

Environment  variable  name  s  used  or  created  by  an  application  should  consist 
solely  of  characters  from  the  portable  filename  character  set.  Other  characters 
may  be  permitted  by  an  implementation;  applications  shall  tolerate  the  presence 
of  such  names.  Upper-  and  lowercase  letters  retain  their  unique  identities  and 
are  not  folded  together.  System-defined  environment  variable  names  should 
begin  with  a  capital  letter  or  underscore  and  be  composed  of  only  capital  letters, 
underscores,  and  numbers. 

The  values  that  the  environment  variables  may  be  assigned  are  not  restricted 
except  that  they  are  considered  to  end  with  a  null  byte,  and  the  total  space  used 
to  store  the  environment  and  the  arguments  to  the  process  is  limited  to 
{ARG_MAX}  bytes. 

Other  name  =  value  pairs  may  be  placed  in  the  environment  by  manipulating  the 
environ  variable  or  by  using  envp  arguments  when  creating  a  process  (see  3.1.2). 


2.7  C  Language  Definitions 


2.7.1  Symbols  From  the  C  Standard 

The  following  terms  and  symbols  used  in  this  part  of  ISO/IEC  9945  are  defined  in  | 
the  C  Standard  {2}:  NULL,  byte,  array  of  char,  clockjt,  header,  null  character,  \ 
string,  timej.  The  type  clock _t  shall  be  capable  of  representing  all  integer  values  | 
from  zero  to  the  number  of  clock  ticks  in  24  h. 

The  term  NULL  pointer  in  this  part  of  ISO/IEC  9945  is  equivalent  to  the  term  null 
pointer  used  in  the  C  Standard  {2}.  The  symbol  NULL  shall  be  declared  in 
<unistd.h>  with  the  same  value  as  required  by  the  C  Standard  {2},  in  addition 
to  several  headers  already  required  by  the  C  Standard  {2}.  | 

Additionally,  the  reservation  of  symbols  that  begin  with  an  underscore  applies: 

(1)  All  external  identifiers  that  begin  with  an  underscore  are  reserved. 

(2)  All  other  identifiers  that  begin  with  an  underscore  and  either  an  upper¬ 
case  letter  or  another  underscore  are  reserved. 

(3)  If  the  program  defines  an  external  identifier  with  the  same  name  as  a 
reserved  external  identifier,  even  in  a  semantically  equivalent  form,  the 
behavior  is  undefined. 

Certain  other  namespaces  are  reserved  by  the  C  Standard  {2}.  These  reservations 
apply  to  this  part  of  ISO/IEC  9945  as  well.  Additionally,  the  C  Standard  {2} 
requires  that  it  be  possible  to  include  a  header  more  than  once  and  that  a  symbol 
may  be  defined  in  more  than  one  header.  This  requirement  is  also  made  of 
headers  for  this  part  of  ISO/IEC  9945. 
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2.7.2  POSIX.  1  Symbols 


Certain  symbols  in  this  part  of  ISO/IEC  9945  are  defined  in  headers.  Some  of  | 
those  headers  could  also  define  other  symbols  than  those  defined  by  this  part  of  | 
ISO/IEC  9945,  potentially  conflicting  with  symbols  used  by  the  application.  Also,  | 
this  part  of  ISO/IEC  9945  defines  symbols  that  are  not  permitted  by  other  stan-  | 
dards  to  appear  in  those  headers  without  some  control  on  the  visibility  of  those 
symbols. 

Symbols  called  feature  test  macros  are  used  to  control  the  visibility  of  symbols 
that  might  be  included  in  a  header.  Implementations,  future  versions  of  this  part 
of  ISO/IEC  9945,  and  other  standards  may  define  additional  feature  test  macros. 
Feature  test  macros  shall  be  defined  in  the  compilation  of  an  application  before  an 
#include  of  any  header  where  a  symbol  should  be  visible  to  some,  but  not  all, 
applications.  If  the  definition  of  the  macro  does  not  precede  the  fin  elude,  the 
result  is  undefined. 


Feature  test  macros  shall  begin  with  the  underscore  character  ( _ ). 


Implementations  may  add  symbols  to  the  headers  shown  in  Table  2-2,  provided 
the  identifiers  for  those  symbols  begin  with  the  corresponding  reserved  prefixes  in 
Table  2-2.  Similarly,  implementations  may  add  symbols  to  the  headers  in 
Table  2-2  that  end  in  the  string  indicated  as  a  reserved  suffix  as  long  as  the 
reserved  suffix  is  in  that  part  of  the  name  considered  significant  by  the  implemen¬ 
tation.  This  shall  be  in  addition  to  any  reservations  made  in  the  C  Standard  {2}. 

If  any  header  defined  by  this  part  of  ISO/IEC  9945  is  included,  all  symbols  with 
the  suffix  _t  are  reserved  for  use  by  the  implementation,  both  before  and  after  the 
finclude  directive. 

After  the  last  inclusion  of  a  given  header,  an  application  may  use  any  of  the  sym¬ 
bol  classes  reserved  in  Table  2-2  for  its  own  purposes,  as  long  as  the  requirements 
in  the  note  to  Table  2-2  are  satisfied,  noting  that  the  symbol  declared  in  the 
header  may  become  inaccessible. 

Future  revisions  of  this  part  of  ISO/IEC  9945,  and  other  POSIX  standards,  are 
likely  to  use  symbols  in  these  same  reserved  spaces. 

In  addition,  implementations  may  add  members  to  a  structure  or  union  without 
controlling  the  visibility  of  those  members  with  a  feature  test  macro,  as  long  as  a 
user-defined  macro  with  the  same  name  cannot  interfere  with  the  correct 
interpretation  of  the  program. 

The  header  <fcntl.h>  may  contain  the  following  symbols  in  addition  to  those 
specifically  required  elsewhere  in  POSIX.1: 


SEEK_CUR 

SEEK.END 

SEEKJ3ET 

S_IRGRP 

SJROTH 


S_IRUSR 

S_IRWXG 

SJRWXO 

SJRWXU 

S_ISBLK 


S_ISCHR 

S.ISDIR 

S_ISFIFO 

S_ISGID 


S_ISREG 

S_ISUID 

S_IWGRP 

S.IWOTH 


S_IWUSR 

S_IXGRP 

S_IXOTH 

S_IXUSR 


In  addition,  an  implementation  may  define  the  symbols  “cuserid”  in  <unistd. h> 
and  “L_cuserid”  in  <stdio  .  h>. 
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826 

827 

828 

829 

Table  2-2  - 

Reserved  Header  Symbols 

Header 

Key 

Reserved 

Prefix 

Reserved 

Suffix 

830 

<dirent .h> 

l 

d 

831 

<f cntl . h> 

l 

1 

832 

2 

F 

833 

2 

O 

834 

2 

S 

835 

<grp .h> 

1 

9r_ 

836 

Climit s . h> 

1 

MAX 

837 

<locale.h> 

2 

LC  [A-Z] 

838 

<pwd.h> 

1 

pw 

839 

<signal .h> 

1 

sa_ 

840 

2 

SIG 

841 

2 

SA 

842 

<sys/stat .h> 

1 

St 

843 

2 

S 

844 

<sys /times . h> 

1 

tms 

845 

Ctermios .h> 

1 

c 

846 

2 

V 

847 

2 

i 

848 

2 

0 

849 

2 

TC 

850 

2 

B  [  0-9 ] 

851 

any  POSIX.  1  header  included 

1 

t 

852 

853 

854 

855 

856 

857 

NOTE:  The  notation  “[0-9]”  indicates  any  digit  and  “[A-Z]”  any  uppercase  character  in  the  portable 
filename  character  set.  The  Key  values  are: 

(1)  Prefixes  and  suffixes  of  symbols  that  shall  not  be  declared  or  #def  ined  by  the  application. 

(2)  Prefixes  and  suffixes  of  symbols  that  shall  be  preceded  in  the  application  with  a  #undef  of 
that  symbol  before  any  other  use. 

858  The  following  feature  test  macro  is  defined: 


859 

860 
861 
862 

863 

864 

865 

866 

867 

868 

869 

870 

871 


Name 


POSIX  SOURCE 


Description 


When  an  application  includes  a  header  described  by 
POSIX.  1,  and  when  this  feature  test  macro  is  defined 
according  to  the  preceding  rules: 

(1)  All  symbols  required  by  POSIX.  1  to  appear  when 
the  header  is  included  shall  be  made  visible. 

(2)  Symbols  that  are  explicitly  permitted,  but  not 
required,  by  POSIX.  1  to  appear  in  that  header 
(including  those  in  reserved  namespaces)  may  be 
made  visible. 

(3)  Additional  symbols  not  required  or  explicitly  per¬ 
mitted  by  POSIX.  1  to  be  in  that  header  shall  not 
be  made  visible. 
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The  exact  meaning  of  feature  test  macros  depends  on  the  type  of  C  language  sup¬ 
port  chosen:  C  Standard  Language-Dependent  Support  and  Common-Usage-  | 
Dependent  Support,  described  in  the  following  two  subclauses.  J 

2.7.2.1  C  Standard  Language-Dependent  Support 

If  there  are  no  feature  test  macros  present  in  a  program,  the  implementation  | 
shall  make  visible  only  those  identifiers  specified  as  reserved  identifiers  in  the  | 
C  Standard  {2},  permitting  the  reservation  of  symbols  and  namespace  defined  in  | 
2.7.1.  For  each  feature  test  macro  present,  only  the  symbols  specified  by  that 
feature  test  macro  plus  those  of  the  C  Standard  {2}  shall  be  defined  when  a  header 
is  included. 

2.7.2.2  Common-Usage-Dependent  Support 

If  the  feature  test  macro  _POSIX_SOURCE  is  not  defined  in  a  program,  the  set  of 
symbols  defined  in  each  header  that  are  beyond  the  requirements  of  this  part  of  | 
ISO/IEC  9945  is  unspecified.  j 

If  _POSIX_SOURCE  is  defined  before  any  header  is  included,  no  symbols  other 
than  those  from  the  C  Standard  {2}  and  those  made  visible  by  feature  test  macros 
defined  for  the  program  (including  _POSIX_SOURCE)  will  be  visible.  Symbols  from  | 
the  namespace  reserved  for  the  implementation,  as  defined  by  the  C  Standard  {2},  | 

are  also  permitted.  The  symbols  beginning  with  two  underscores  are  examples  of  | 
this.  j 

If  _POSIX_SOURCE  is  not  defined  before  any  header  is  included,  the  behavior  is 
undefined. 


2.7.3  Headers  and  Function  Prototypes 

Implementations  claiming  C  Standard  {2}  Language-Dependent  Support  shall 
declare  function  prototypes  for  all  functions. 

Implementations  claiming  Common-Usage  C  Language-Dependent  Support  shall 
declare  the  result  type  for  all  functions  not  returning  a  “plain”  int. 

For  functions  described  in  the  C  Standard  {2}  and  included  by  reference  in  Section 
8  (whether  or  not  they  are  further  described  in  this  part  of  ISO/IEC  9945),  these 
prototypes  or  declarations  (if  required)  shall  appear  in  the  headers  defined  for 
them  in  the  C  Standard  {2}.  For  other  functions  in  this  part  of  ISO/IEC  9945,  the 
prototypes  or  declarations  shall  appear  in  the  headers  listed  below.  If  a  function 
is  defined  by  this  part  of  ISO/IEC  9945,  is  not  described  in  the  C  Standard  {2},  and 
is  not  listed  below,  it  shall  have  its  prototype  or  declaration  (if  required)  appear  in 
<unistd.h>,  which  shall  be  #include-ed  by  the  application  before  using  any 
function  declared  in  it,  whether  or  not  it  is  mentioned  in  the  Synopsis  subclause 
for  that  function.  The  requirements  about  the  visibility  of  symbols  in  2.7.2  shall 
be  honored. 
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910 

<dirent . h> 

opendir( ),  readdiri ),  rewinddir( ),  closedir( ) 

911 

<f cnt 1 . h> 

open  ( ),  create ),  fcntli ) 

912 

<grp . h> 

getgrgidi ),  getgrnami) 

913 

<pwd . h> 

getpwuidi),  getpwnamO 

914 

<set jmp . h> 

sigsetjmpi ),  siglongjmpi ) 

916 

916 

917 

<signal . h> 

kill{),  sigemptysetO,  sigfillsetO,  sigaddsetO,  sigdelsetO, 
sigismemberi),  sigaction(),  sigprocmaski),  sigpendingO, 
sigsuspendO 

918 

<stdio . h> 

ctermidi),  filenoO,  fdopeni) 

919 

<sys/ stat . h> 

umaskO,  mkdirO,  mkfifoO,  stat(),  fstat(),  chmodO 

920 

<sys/ times . h> 

times() 

921 

<sys/ut sname . h> 

uname{) 

922 

<sys/wait . h> 

wait{),  waitpidi) 

923 

924 

925 

ctermios . h> 

cfgetospeedi),  cfsetospeedi),  cfgetispeedi),  cfsetispeedi), 
tcgetattrO,  tcsetattr(),  tcsendbreak (),  tcdrain (), 
tcflushi),  tcflowi) 

926 

<time . h> 

time  (),  tzset  () 

927 

<utime . h> 

utimeO 

928  The  declarations  in  the  headers  shall  follow  the  proper  form  for  the  C  language 

929  option  chosen  by  the  implementation.  Additionally,  pointer  arguments  that  refer 

930  to  objects  not  modified  by  the  function  being  described  are  declared  with  const 

931  qualifying  the  type  to  which  it  points.  Implementations  claiming  Common-Usage 

932  C  conformance  to  this  part  of  ISO/IEC  9945  may  ignore  the  presence  of  this  key- 

933  word  and  need  not  include  it  in  any  function  declarations.  Implementations 

934  claiming  conformance  using  the  C  Standard  {2}  shall  use  the  const  modifier  as 

935  indicated  in  the  prototypes  they  provide. 

936  Implementations  claiming  conformance  using  Common-Usage  C  may  use 

937  equivalent  implementation-defined  constructs  when  void  is  used  as  a  result  type 

938  for  a  function  prototype.  They  may  also  use  int  when  a  function  result  is  declared 

939  ssizejt. 

940  Neither  the  names  of  the  formal  parameters  nor  their  types,  as  they  appear  in  an 

941  implementation,  are  specified  by  this  part  of  ISO/IEC  9945.  The  names  are  used 

942  within  this  part  of  ISO/IEC  9945  as  a  notational  mechanism.  However,  any 

943  declaration  provided  by  an  implementation  shall  accept  all  actual  parameter 

944  types  that  a  declaration  lexically  identical  to  one  in  this  part  of  ISO/IEC  9945  shall 

945  accept,  including  the  effects  of  both  type  conversion  and  checking  for  the  number 

946  of  arguments  implied  by  the  presence  of  a  filled-out  prototype.  The 

947  implementation’s  declaration  shall  not  cause  a  syntax  error  if  an  application  pro- 

948  vides  a  prototype  lexically  identical  to  one  in  this  part  of  ISO/IEC  9945.  It  is  not  a 

949  requirement  that  nonconforming  parameters  to  functions  that  may  be  used  by  an 

950  application  be  diagnosed  by  an  implementation,  except  as  specifically  required  by 

951  this  part  of  ISO/IEC  9945  or  the  C  Standard  {2},  as  applicable.  Where  the 
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952  C  Standard  {2}  has  a  more  restrictive  requirement  for  a  function  defined  by  that  | 

953  standard,  that  requirement  shall  be  honored,  and  this  exception  does  not  apply. 


954  2.8  Numerical  Limits 

955  The  following  subclauses  list  magnitude  limitations  imposed  by  a  specific  imple-  | 

956  mentation.  The  braces  notation,  {LIMIT},  is  used  in  this  part  of  ISO/IEC  9945  to 

957  indicate  these  values,  but  the  braces  are  not  part  of  the  name. 

958  2.8.1  C  Language  Limits 

959  The  following  limits  used  in  this  part  of  ISO/IEC  9945  are  defined  in  the  | 

960  C  Standard  {2}:  {CHAR_BIT},  {CHAR_MAX},  {CHAR_MIN},  {INT_MAX},  (INT_MIN),  | 

961  {LONG_MAX},  {LQNG_MIN},  {MB_LEN_MAX} ,  {SCHAR_MAX},  {SCHAR_MIN}, 

962  {SHRT_MAX},  {SHRT_MIN},  {UCHAR_MAX},  {UINT_MAX},  {ULONG.MAX}, 

963  {USHRT_MAX}. 

964  2.8.2  Minimum  Values 

965  The  symbols  in  Table  2-3  shall  be  defined  in  < limits  . h>  with  the  values  shown. 

966  These  are  symbolic  names  for  the  most  restrictive  value  for  certain  features  on  a 

967  system  conforming  to  this  part  of  ISO/IEC  9945.  Related  symbols  are  defined  else- 

968  where  in  this  part  of  ISO/IEC  9945,  which  reflect  the  actual  implementation  and 

969  which  need  not  be  as  restrictive.  A  conforming  implementation  shall  provide 

970  values  at  least  this  large.  A  portable  application  shall  not  require  a  larger  value 

971  for  correct  operation. 

972  2.8.3  Run-Time  Increasable  Values 

973  The  magnitude  limitations  in  Table  2-4  shall  be  fixed  by  specific  implementations. 

974  A  Strictly  Conforming  POSIX.  1  Application  shall  assume  that  the  value  supplied 

975  by  < limits  .h>  in  a  specific  implementation  is  the  minimum  value  that  pertains 

976  whenever  the  Strictly  Conforming  POSIX.  1  Application  is  run  under  that  imple- 

977  mentation. 3)  A  specific  instance  of  a  specific  implementation  may  increase  the 

978  value  relative  to  that  supplied  by  <limits.h>  for  that  implementation.  The 

979  actual  value  supported  by  a  specific  instance  shall  be  provided  by  the  sysconfi) 

980  function. 


981  3)  In  a  future  revision  of  this  part  of  ISO/IEC  9945,  omitting  a  symbol  defined  in  this  subclause  from 

982  climits  .h>  is  expected  to  indicate  that  the  value  is  variable. 
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Table  2-3  -  Minimum  Values 


Name 

Description 

Value 

Lposix_arg_max} 

The  length  of  the  arguments  for  one  of  the  exec  func¬ 
tions,  in  bytes,  including  environment  data. 

4096 

LPOSIX_CfflLD_MAX) 

The  number  of  simultaneous  processes  per  real  user 

ID 

6 

LPOSIX_LINK_MAX} 

The  value  of  a  file’s  link  count. 

8 

{_POSIX_MAX_CANON} 

The  number  of  bytes  in  a  terminal  canonical  input 
queue. 

255 

LPOSIX_MAX_INPUT} 

The  number  of  bytes  for  which  space  will  be  available 
in  a  terminal  input  queue. 

255 

{_POSEX_NAME_MAX} 

The  number  of  bytes  in  a  filename. 

14 

LPOSIX_NGROUPS_MAX) 

The  number  of  simultaneous  supplementary  group  IDs 
per  process. 

0 

l_POSIX_OPEN_MAX} 

The  number  of  files  that  one  process  can  have  open  at 
one  time. 

16 

LPOSIX_PATH_MAX} 

The  number  of  bytes  in  a  pathname. 

255 

LPOSIX_PIPE_BUF} 

The  number  of  bytes  that  can  be  written  atomically 
when  writing  to  a  pipe. 

512 

LPOSIX_SSIZE_MAX} 

The  value  that  can  be  stored  in  an  object  of  type 
ssizejt. 

32  767 

LPOSIX_STREAM_MAX) 

The  number  of  streams  that  one  process  can  have 
open  at  one  time. 

8 

LPOSIX_TZNAME_MAX} 

The  maximum  number  of  bytes  supported  for  the 
name  of  a  time  zone  (not  of  the  TZ  variable). 

3 

Table  2-4  -  Run-Time  Increasable  Values 

Name 

Description 

Minimum  Value 

(NGROUPS_MAX) 

Maximum  number  of  simultaneous  supple¬ 
mentary  group  IDs  per  process. 

LPOSIX_NGROUPS_MAX} 

2.8.4  Run-Time  Invariant  Values  (Possibly  Indeterminate) 

A  definition  of  one  of  the  values  in  Table  2-5  shall  be  omitted  from  the 
climits  .h>  on  specific  implementations  where  the  corresponding  value  is  equal 
to  or  greater  than  the  stated  minimum,  but  is  indeterminate. 

This  might  depend  on  the  amount  of  available  memory  space  on  a  specific 
instance  of  a  specific  implementation.  The  actual  value  supported  by  a  specific 
instance  shall  be  provided  by  the  sysconfi )  function. 
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Table  2-5  -  Run-Time  Invariant  Values  (Possibly  Indeterminate) 


Name 

Description 

Minimum  Value 

(ARG_MAX) 

Maximum  length  of  arguments  for  the  exec 
functions,  in  bytes,  including  environment 
data. 

{_POSIX_ARG_MAX} 

(CHILD_MAX) 

Maximum  number  of  simultaneous 
processes  per  real  user  ID. 

LPOSIX_CHILD_MAX} 

{OPEN_MAX} 

Maximum  number  of  files  that  one  process 
can  have  open  at  any  given  time. 

{_POSIX_OPEN_MAX} 

{STREAM.MAX} 

The  number  of  streams  that  one  process 
can  have  open  at  one  time.  If  defined,  it 
shall  have  the  same  value  as 
{FOPEN_MAX}  from  the  C  Standard  {2}. 

LPOSIX_STREAM_MAX} 

{TZNAME_MAX} 

The  maximum  number  of  bytes  supported 
for  the  name  of  a  time  zone  (not  of  the  TZ 
variable). 

LPOSK_TZNAME_MAX) 

2.8.5  Pathname  Variable  Values 

The  values  in 

Table  2-6  may  be  constants  within  an  implementation  or  may  vary 

from  one  pathname  to  another. 

Table  2-6  -  Pathname  Variable  Values 

Name 

Description 

Minimum  Value 

{LINK_MAX} 

Maximum  value  of  a  file’s  link  count. 

LPOSIX_LINK_MAX} 

{MAX_C  AN  ON} 

Maximum  number  of  bytes  in  a  terminal 
canonical  input  line.  (See  7. 1.1. 6.) 

(_POSIX_MAX_CAN  ON) 

(MAXJNPUT) 

Minimum  number  of  bytes  for  which  space 
will  be  available  in  a  terminal  input 
queue;  therefore,  the  maximum  number  of 
bytes  a  portable  application  may  require  to 
be  typed  as  input  before  reading  them. 

LPOSIX_MAX_INPUT} 

{NAME_MAX} 

Maximum  number  of  bytes  in  a  file  name 
(not  a  string  length;  count  excludes  a  ter¬ 
minating  null). 

LPOSIX_NAME_MAX} 

{PATH_MAX} 

Maximum  number  of  bytes  in  a  pathname 
(not  a  string  length;  count  excludes  a  ter¬ 
minating  null). 

l_POSIX_PATH_MAX} 

{PIPE_BUF} 

Maximum  number  of  bytes  that  can  be 
written  atomically  when  writing  to  a  pipe. 

LPOSIX_PIPE_BUF} 

For  example,  file  systems  or  directories  may  have  different  characteristics. 

A  definition  of  one  of  the  values  from  Table  2-6  shall  be  omitted  from 
<limits  .  h>  on  specific  implementations  where  the  corresponding  value  is  equal 
to  or  greater  than  the  stated  minimum,  but  where  the  value  can  vary  depending 
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1068  on  the  file  to  which  it  is  applied.  The  actual  value  supported  for  a  specific  path- 

1069  name  shall  be  provided  by  the  pathconfi )  function. 

1070  2.8.6  Invariant  Values 

1071  The  value  in  Table  2-7  shall  not  vary  in  a  given  implementation.  The  value  in 

1072  that  table  shall  appear  in  < limits  .  h>. 


1073 

1074 

Table  2-7  -  Invariant  Value 

1075  Name 

Description 

Value 

1076  {SSIZE_MAX} 

1077 

1078 

The  maximum  value  that  can  be  stored  in  an 
object  of  type  ssize_t. 

LPOSIX_SSIZE_MAX} 

1079  2.9  Symbolic  Constants 

1080  A  conforming  implementation  shall  have  the  header  <unistd.h>.  This  header 

1081  defines  the  symbolic  constants  and  structures  referenced  elsewhere  in  this  part  of 

1082  ISO/IEC  9945.  The  constants  defined  by  this  header  are  shown  in  the  following 

1083  subclauses.  The  actual  values  of  the  constants  are  implementation  defined. 

1084  2.9.1  Symbolic  Constants  for  the  access  ()  Function 

1085  The  constants  used  by  the  accessi)  function  are  shown  in  Table  2-8.  The  con- 

1086  stants  F_OK,  R_OK,  W_OK,  and  X_OK,  and  the  expressions 

1087  R_OK  |  W_OK 

1088  (where  the  |  represents  the  bitwise  inclusive  OR  operator), 

1089  R_OK  |  X_OK 

1090  and 

1091  R_OK  |  W_OK  |  X_OK 

1092  shall  all  have  distinct  values. 

1093  2.9.2  Symbolic  Constant  for  the  Iseek  ( )  Function 

1094  The  constants  used  by  the  IseekO  function  are  shown  in  Table  2-9. 
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1095 

1096 

Table  2-8  -  Symbolic  Constants  for  the  access  ()  Function 

1097 

Constant 

Description 

1098 

R_OK 

Test  for  read  permission. 

1099 

W_OK 

Test  for  write  permission. 

1100 

X_OK 

Test  for  execute  or  search  permission. 

1101 

F_OK 

Test  for  existence  of  file. 

1102 

1103  Table  2-9  -  Symbolic  Constants  for  the  Iseek  ( )  Function 

1104  _ 

1105  Constant  Description 

1106  SEEK_SET  Set  file  offset  to  offset. 

1107  SEEK_CUR  Set  file  offset  to  current  plus  offset. 

1108  SEEK_END  Set  file  offset  to  EOF  plus  offset. 

1109  _ 


mo  2.9.3  Compile-Time  Symbolic  Constants  for  Portability  Specifications 

mi  The  constants  in  Table  2-10  may  be  used  by  the  application,  at  compile  time,  to 

1112  determine  which  optional  facilities  are  present  and  what  actions  shall  be  taken  by 

1113  the  implementation. 


ni4  Table  2-10  -  Compile-Time  Symbolic  Constants 

1115  _ 


1116 

Name 

Description 

1117 

1118 

LPOSIX_JOB_CONTROL} 

If  this  symbol  is  defined,  it  indicates  that  the  implementation  sup¬ 
ports  job  control. 

1119 

{_POSIX_SAVED_IDS} 

If  defined,  each  process  has  a  saved  set-user-ID  and  a  saved  set- 

1120 

group-ID. 

1121 

1122 

LPOSKVERSION) 

The  integer  value  199009L.  This  value  shall  be  used  for  systems 
that  conform  to  this  part  of  ISO/IEC  9945. 

1123 

1124  Although  a  Strictly  Conforming  POSIX.1  Application  can  rely  on  the  values  com- 

1125  piled  from  the  <unistd.h>  header  to  afford  it  portability  on  all  instances  of  an 

1126  implementation,  it  may  choose  to  interrogate  a  value  at  run-time  to  take  advan- 
U27  tage  of  the  current  configuration.  See  4.8.1. 

H28  2.9.4  Execution-Time  Symbolic  Constants  for  Portability  Specifications 

1129  The  constants  in  Table  2-11  may  be  used  by  the  application,  at  execution  time,  to 
U30  determine  which  optional  facilities  are  present  and  what  actions  shall  be  taken  by 
U3i  the  implementation  in  some  circumstances  described  by  this  part  of  ISO/IEC  9945 
1132  as  implementation  defined . 
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1133 

1134 

Table  2-11  - 

Execution-Time  Symbolic  Constants 

1135 

Name 

Description 

1136 

1137 

1138 

1139 

(_POSIX_CHOWN_RESTRICTED) 

The  use  of  the  chown{)  function  is  restricted  to  a  process 
with  appropriate  privileges,  and  to  changing  the  group  ID  of 
a  file  only  to  the  effective  group  ID  of  the  process  or  to  one  of 
its  supplementary  group  IDs. 

1140 

1141 

LPOSIX_NO_TRUNC} 

Pathname  components  longer  than  {NAME_MAX}  generate 
an  error. 

1142 

1143 

1144 

1145 

LPOSIXVDISABLE} 

Terminal  special  characters  defined  in  7. 1.1.9  can  be  dis¬ 
abled  using  this  character  value,  if  it  is  defined.  See 
tcgetattrO  and  tcsetattr(). 

1146  If  any  of  the  constants  in  Table  2-11  are  not  defined  in  the  header  <unistd.h>, 

1147  the  value  varies  depending  on  the  file  to  which  it  is  applied.  See  5.7.1. 

U48  If  any  of  the  constants  in  Table  2-11  are  defined  to  have  value  -1  in  the  header 

1149  <unistd.h>,  the  implementation  shall  not  provide  the  option  on  any  file;  if  any 

1150  are  defined  to  have  a  value  other  than  -1  in  the  header  <unistd.h>,  the  imple- 
U5i  mentation  shall  provide  the  option  on  all  applicable  files. 

U52  All  of  the  constants  in  Table  2-11,  whether  defined  in  <unistd .  h>  or  not,  may  be 
1153  queried  with  respect  to  a  specific  file  using  the  pathconfi )  or  fpathconfi )  functions. 
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Section  3:  Process  Primitives 


The  functions  described  in  this  section  perform  the  most  primitive  operating  sys¬ 
tem  services  dealing  with  processes,  interprocess  signals,  and  timers.  All  attri¬ 
butes  of  a  process  that  are  specified  in  this  part  of  ISO/IEC  9945  shall  remain 
unchanged  by  a  process  primitive  unless  the  description  of  that  process  primitive 
states  explicitly  that  the  attribute  is  changed. 


3.1  Process  Creation  and  Execution 


3.1.1  Process  Creation 

Function:  fork() 

3. 1.1.1  Synopsis 

♦include  <sys/types . h> 

pid_t  fork (void); 

3. 1.1.2  Description 

The  fork ()  function  creates  a  new  process.  The  new  process  (child  process)  shall 

be  an  exact  copy  of  the  calling  process  (parent  process)  except  for  the  following: 

(1)  The  child  process  has  a  unique  process  ID.  The  child  process  ID  also  does 
not  match  any  active  process  group  ID. 

(2)  The  child  process  has  a  different  parent  process  ID  (which  is  the  process 
ID  of  the  parent  process). 

(3)  The  child  process  has  its  own  copy  of  the  parent’s  file  descriptors.  Each 
of  the  child’s  file  descriptors  refers  to  the  same  open  file  description  with 
the  corresponding  file  descriptor  of  the  parent. 

(4)  The  child  process  has  its  own  copy  of  the  parent’s  open  directory  streams 
(see  5.1.2).  Each  open  directory  stream  in  the  child  process  may  share 
directory  stream  positioning  with  the  corresponding  directory  stream  of 
the  parent. 

(5)  The  child  process’s  values  of  tmsjutime,  tms_stime,  tmsjcutime ,  and 
tmsjcstime  are  set  to  zero  (see  4.5.2). 
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28  (6)  File  locks  previously  set  by  the  parent  are  not  inherited  by  the  child. 

29  (See  6.5.2.) 


30 

31 

32 


(7)  Pending  alarms  are  cleared  for  the  child  process.  (See  3.4.1.) 

(8)  The  set  of  signals  pending  for  the  child  process  is  initialized  to  the  empty 
set.  (See  3.3.1.) 


33  All  other  process  characteristics  defined  by  this  part  of  ISO/IEC  9945  shall  be  the 

34  same  in  the  parent  and  the  child  processes.  The  inheritance  of  process  charac- 

35  teristics  not  defined  by  this  part  of  ISO/IEC  9945  is  unspecified  by  this  part  of 

36  ISO/IEC  9945,  but  should  be  documented  in  the  system  documentation. 

37  After  fork (),  both  the  parent  and  the  child  processes  shall  be  capable  of  executing 

38  independently  before  either  terminates. 


39  3. 1.1.3  Returns 

40  Upon  successful  completion,  fork()  shall  return  a  value  of  zero  to  the  child  process 

41  and  shall  return  the  process  ID  of  the  child  process  to  the  parent  process.  Both 

42  processes  shall  continue  to  execute  from  the  forki)  function.  Otherwise,  a  value  of 

43  -1  shall  be  returned  to  the  parent  process,  no  child  process  shall  be  created,  and 

44  errno  shall  be  set  to  indicate  the  error. 

45  3.1. 1.4  Errors 

46  If  any  of  the  following  conditions  occur,  the  forkf)  function  shall  return  -1  and  set 

47  errno  to  the  corresponding  value: 

48  [E AGAIN]  The  system  lacked  the  necessary  resources  to  create  another 

49  process,  or  the  system-imposed  limit  on  the  total  number  of 

50  processes  under  execution  by  a  single  user  would  be  exceeded. 

51  For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  fork{)  func- 

52  tion  shall  return  -1  and  set  errno  to  the  corresponding  value: 

53  [ENOMEM]  The  process  requires  more  space  than  the  system  is  able  to 

54  supply. 

55  3.1. 1.5  Cross-References 

56  alarmO,  3.4.1;  exec,  3.1.2;  fcntl{),  6.5.2;  kill(),  3.3.2;  timesO,  4.5.2;  wait,  3.2.1. 


57  3.1.2  Execute  a  File 

58  Functions:  ex ecl{ ),  execv(),  execleO,  execvei ),  execlpi),  execvpi). 

59  3. 1.2.1  Synopsis 

60  int  execl  (const  char  *path,  const  char  *arg ,  .  .  .  ); 

61  int  execv(const  char  *path,  char  *const  argv  [  ]  )  ; 
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62 

63 

64 

65 


int  execle (const 
int  execve (const 
int  execlp (const 
int  execvp (const 


char  *path,  const  char  *arg,  .  .  .  )  ; 

char  *path,  char  *const  argu  [  ]  ,  char  *const  envp  [  ]  )  ; 
char  *file,  const  char  *arg ,  .  .  .  )  ; 
char  *file ,  char  *const  argv  [  ]  )  ; 


66  3. 1.2.2  Description 

67  The  exec  family  of  functions  shall  replace  the  current  process  image  with  a  new 

68  process  image.  The  new  image  is  constructed  from  a  regular,  executable  file 

69  called  the  new  process  image  file .  There  shall  be  no  return  from  a  successful  exec 

70  because  the  calling  process  image  is  overlaid  by  the  new  process  image. 

71  When  a  C  program  is  executed  as  a  result  of  this  call,  it  shall  be  entered  as  a  C 

72  language  function  call  as  follows: 

73  int  main  (int  argc ,  char  *argv  [  ]  )  ; 

74  where  argc  is  the  argument  count  and  argv  is  an  array  of  character  pointers  to 

75  the  arguments  themselves.  In  addition,  the  following  variable: 

76  extern  char  **environ; 

77  is  initialized  as  a  pointer  to  an  array  of  character  pointers  to  the  environment 

78  strings.  The  argv  and  environ  arrays  are  each  terminated  by  a  NULL  pointer. 

79  The  NULL  pointer  terminating  the  argv  array  is  not  counted  in  argc . 

so  The  arguments  specified  by  a  program  with  one  of  the  exec  functions  shall  be 

81  passed  on  to  the  new  process  image  in  the  corresponding  main{)  arguments. 

82  The  argument  path  points  to  a  pathname  that  identifies  the  new  process  image 

83  file. 

84  The  argument  file  is  used  to  construct  a  pathname  that  identifies  the  new  process 

85  image  file.  If  the  file  argument  contains  a  slash  character,  the  file  argument  shall  | 

86  be  used  as  the  pathname  for  this  file.  Otherwise,  the  path  prefix  for  this  file  is  | 

87  obtained  by  a  search  of  the  directories  passed  as  the  environment  variable  PATH  | 

88  (see  2.6).  If  this  environment  variable  is  not  present,  the  results  of  the  search  are 

89  implementation  defined. 

90  | 

91  The  argument  argv  is  an  array  of  character  pointers  to  null-terminated  strings. 

92  The  last  member  of  this  array  shall  be  a  NULL  pointer.  These  strings  constitute 

93  the  argument  list  available  to  the  new  process  image.  The  value  in  argv  [0]  should 

94  point  to  a  filename  that  is  associated  with  the  process  being  started  by  one  of  the 

95  exec  functions. 

96  The  const  char  *arg  and  subsequent  ellipses  in  the  execlO,  execlpO,  and  exe-  \ 

97  cle  ()  functions  can  be  thought  of  as  argO,  argl ,  . . . ,  argn.  Together  they  describe  | 

98  a  list  of  one  or  more  pointers  to  null-terminated  character  strings  that  represent  | 

99  the  argument  list  available  to  the  new  program.  The  first  argument  should  point  | 

100  to  a  filename  that  is  associated  with  the  process  being  started  by  one  of  the  exec  | 

101  functions,  and  the  last  argument  shall  be  a  NULL  pointer.  For  the  execlei)  func-  | 

102  tion,  the  environment  is  provided  by  following  the  NULL  pointer  that  shall  ter-  | 

103  minate  the  list  of  arguments  in  the  parameter  list  to  execle  ()  with  an  additional  | 
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104  parameter,  as  if  it  were  declared  as 

105  char  *const  envp  [  ] 

106  The  argument  envp  to  execve ()  and  the  final  argument  to  execle ()  name  an  array  | 

107  of  character  pointers  to  null-terminated  strings.  These  strings  constitute  the  | 

108  environment  for  the  new  process  image.  The  environment  array  is  terminated  by  | 

109  a  NULL  pointer.  I 

no  For  those  forms  not  containing  an  envp  pointer  [execli),  execv(),  execlpO,  and 
in  execvp ()1,  the  environment  for  the  new  process  image  is  taken  from  the  external 

112  variable  environ  in  the  calling  process. 

113  The  number  of  bytes  available  for  the  new  process’s  combined  argument  and 

114  environment  fists  is  {ARG_MAX}.  The  implementation  shall  specify  in  the  system 

115  documentation  (see  1.3. 1.2)  whether  any  combination  of  null  terminators, 

116  pointers,  or  alignment  bytes  are  included  in  this  total. 

117  File  descriptors  open  in  the  calling  process  image  remain  open  in  the  new  process 
H8  image,  except  for  those  whose  close-on-exec  flag  FD_CLOEXEC  is  set  (see  6.5.2  and 

119  6.5.1).  For  those  file  descriptors  that  remain  open,  all  attributes  of  the  open  file 

120  description,  including  file  locks  (see  6.5.2),  remain  unchanged  by  this  function 

121  call. 

122  Directory  streams  open  in  the  calling  process  image  shall  be  closed  in  the  new  | 

123  process  image.  | 

124  Signals  set  to  the  default  action  (SIG_DFL)  in  the  calling  process  image  shall  be 

125  set  to  the  default  action  in  the  new  process  image.  Signals  set  to  be  ignored 

126  (SIG_IGN)  by  the  calling  process  image  shall  be  set  to  be  ignored  by  the  new  pro- 

127  cess  image.  Signals  set  to  be  caught  by  the  calling  process  image  shall  be  set  to 

128  the  default  action  in  the  new  process  image  (see  3.3.1). 

129  If  the  set-user-ID  mode  bit  of  the  new  process  image  file  is  set  (see  5.6.4),  the  effec- 

130  tive  user  ID  of  the  new  process  image  is  set  to  the  owner  ID  of  the  new  process 

131  image  file.  Similarly,  if  the  set-group-ID  mode  bit  of  the  new  process  image  file  is 

132  set,  the  effective  group  ID  of  the  new  process  image  is  set  to  the  group  ID  of  the 

133  new  process  image  file.  The  real  user  ID,  real  group  ID,  and  supplementary  group 

134  IDs  of  the  new  process  image  remain  the  same  as  those  of  the  calling  process 

135  image.  If  {_POSIX_SAVED_IDS}  is  defined,  the  effective  user  ID  and  effective 

136  group  ID  of  the  new  process  image  shall  be  saved  (as  the  saved  set-user-ID  and  the 

137  saved  set-group-ID )  for  use  by  the  setuid( )  function. 

138  The  new  process  image  also  inherits  the  following  attributes  from  the  calling  pro- 


139 

cess  image: 

140 

(1) 

Process  ID 

141 

(2) 

Parent  process  ID 

142 

(3) 

Process  group  ID 

143 

(4) 

Session  membership 

144 

(5) 

Real  user  ID 

145 

(6) 

Real  group  ID 
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146 

(7) 

Supplementary  group  IDs 

147 

(8) 

Time  left  until  an  alarm  clock  signal  (see  3.4.1) 

148 

(9) 

Current  working  directory 

149 

(10) 

Root  directory 

150 

(ID 

File  mode  creation  mask  (see  5.3.3) 

151 

(12) 

Process  signal  mask  (see  3.3.5) 

152 

(13) 

Pending  signals  (see  3.3.6) 

153 

(14) 

tms_utime,  tmsjstime,  tmsjcutime ,  and  tms_cstime  (see  4.5.2) 

154  All  process  attributes  defined  by  this  part  of  ISO/IEC  9945  and  not  specified  in  this 

155  subclause  (3.1.2)  shall  be  the  same  in  the  new  and  old  process  images.  The  inher- 

156  itance  of  process  characteristics  not  defined  by  this  part  of  ISO/IEC  9945  is  | 

157  unspecified  by  this  part  of  ISO/IEC  9945,  but  should  be  documented  in  the  system  | 

158  documentation.  | 

159  Upon  successful  completion,  the  exec  functions  shall  mark  for  update  the  st_atime 

160  field  of  the  file.  If  the  exec  function  failed,  but  was  able  to  locate  the  process  image 

161  file ,  whether  the  st_atime  field  is  marked  for  update  is  unspecified.  Should  the 

162  exec  function  succeed,  the  process  image  file  shall  be  considered  to  have  been 

163  open()-e d.  The  corresponding  close ()  shall  be  considered  to  occur  at  a  time  after 

164  this  open,  but  before  process  termination  or  successful  completion  of  a  subsequent 

165  call  to  one  of  the  exec  functions. 

166  The  argv[  ]  and  envp[  ]  arrays  of  pointers  and  the  strings  to  which  those  arrays  | 

167  point  shall  not  be  modified  by  a  call  to  one  of  the  exec  functions,  except  as  a  conse-  | 

168  quence  of  replacing  the  process  image.  | 

169  3. 1.2.3  Returns 

170  If  one  of  the  exec  functions  returns  to  the  calling  process  image,  an  error  has 

171  occurred;  the  return  value  shall  be  -1,  and  errno  shall  be  set  to  indicate  the  error. 


172  3. 1.2.4  Errors 


173  If  any  of  the  following  conditions  occur,  the  exec  functions  shall  return  -1  and  set 

174  errno  to  the  corresponding  value: 


175  [E2BIG] 

176 

177 


The  number  of  bytes  used  by  the  argument  list  and  the  environ¬ 
ment  list  of  the  new  process  image  is  greater  than  the  system- 
imposed  limit  of  {ARG_MAX}  bytes. 


178 

179 

180 
181 
182 


[EACCES]  Search  permission  is  denied  for  a  directory  listed  in  the  path 
prefix  of  the  new  process  image  file,  or  the  new  process  image 
file  denies  execution  permission,  or  the  new  process  image  file 
is  not  a  regular  file  and  the  implementation  does  not  support 
execution  of  files  of  its  type. 


183  [ENAMETOOLONG] 

184  The  length  of  the  path  or  file  arguments,  or  an  element  of  the 


3. 1  Process  Creation  and  Execution 


45 


185 

186 

187 

188 

189 

190 

191 

192 

193 

194 

195 

196 

197 

198 

199 

200 

201 

202 

203 

204 

205 

206 

207 

208 

209 

210 

211 

212 

213 

214 

215 

216 

217 


ISO/IEC  9945-1:  1990 

IEEE  Std  1003.1-1990  INFORMATION  TECHNOLOGY— POSIX 


environment  variable  PATH  prefixed  to  a  file,  exceeds 
{PATH_MAX},  or  a  pathname  component  is  longer  than 
{NAME_MAX}  and  {_POSIX_NO_TRUNC}  is  in  effect  for  that  file. 

[ENOENT]  One  or  more  components  of  the  pathname  of  the  new  process 
image  file  do  not  exist,  or  the  path  or  file  argument  points  to  an 
empty  string. 

[ENOTDIR]  A  component  of  the  path  prefix  of  the  new  process  image  file  is 
not  a  directory. 

If  any  of  the  following  conditions  occur,  the  execli),  execv (),  execlei) ,  and  execve () 
functions  shall  return  -1  and  set  errno  to  the  corresponding  value: 

[ENOEXEC]  The  new  process  image  file  has  the  appropriate  access  permis¬ 
sion,  but  is  not  in  the  proper  format. 

For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  exec  functions 
shall  return  -1  and  return  the  corresponding  value  in  errno : 

[ENOMEM]  The  new  process  image  requires  more  memory  than  is  allowed 
by  the  hardware  or  system-imposed  memory  management  con¬ 
straints. 


3. 1.2.5  Cross-References 

alarmi),  3.4.1;  chmodi),  5.6.4;  jexiti),  3.2.2;  fcntli),  6.5.2;  fork (),  3.1.1;  setuidi), 
4.2.2;  <signal  .h>,  3.3.1;  sigprocmask (),  3.3.5;  sigpending (),  3.3.6;  stat (),  5.6.2; 
<sys/stat .  h>,  5.6.1;  timesi),  4.5.2;  umask (),  5.3.3;  2.6. 


3.2  Process  Termination 

There  are  two  kinds  of  process  termination: 

(1)  Normal  termination  occurs  by  a  return  from  maini)  or  when  requested 
with  the  exit()  or  _exit( )  functions. 

(2)  Abnormal  termination  occurs  when  requested  by  the  aborti)  function  or 
when  some  signals  are  received  (see  3.3.1). 

The  exiti)  and  aborti)  functions  shall  be  as  described  in  the  C  Standard  {2}.  Both  | 
exit()  and  aborti )  shall  terminate  a  process  with  the  consequences  specified  in 
3.2.2,  except  that  the  status  made  available  to  waiti)  or  waitpidi )  by  aborti )  shall 
be  that  of  a  process  terminated  by  the  SIGABRT  signal. 

A  parent  process  can  suspend  its  execution  to  wait  for  termination  of  a  child  pro¬ 
cess  with  the  waiti)  or  waitpidi )  functions. 


46 


3  Process  Primitives 


218 

219 

220 

221 

222 

223 

224 

225 

226 

227 

228 

229 

230 

231 

232 

233 

234 

235 

236 

237 

238 

239 

240 

241 

242 

243 

244 

245 

246 

247 

248 

249 

250 

251 

252 

253 

254 

255 

256 

257 


ISO/IEC  9945-1:  1990 

Part  1:  SYSTEM  API  [C  LANGUAGE]  IEEE  Std  1003.1-1990 

3.2.1  Wait  for  Process  Termination 

Functions:  waiti),  waitpidi) 

3.2.1. 1  Synopsis 

♦include  <sys/types . h> 

♦include  <sys/wait.h> 

pid_t  wait(int  *stat_loc)  ; 

pid_t  waitpid  (pid_t  pid,  int  *stat_loc,  int  options); 


3.2.1.2  Description 

The  waiti)  and  waitpid ()  functions  allow  the  calling  process  to  obtain  status  infor¬ 
mation  pertaining  to  one  of  its  child  processes.  Various  options  permit  status 
information  to  be  obtained  for  child  processes  that  have  terminated  or  stopped.  If 
status  information  is  available  for  two  or  more  child  processes,  the  order  in  which 
their  status  is  reported  is  unspecified. 

The  wait ()  function  shall  suspend  execution  of  the  calling  process  until  status 
information  for  one  of  its  terminated  child  processes  is  available,  or  until  a  signal 
whose  action  is  either  to  execute  a  signal-catching  function  or  to  terminate  the 
process  is  delivered.  If  status  information  is  available  prior  to  the  call  to  waiti ), 
return  shall  be  immediate. 

The  waitpidi)  function  shall  behave  identically  to  the  waiti )  function  if  the  pid 
argument  has  a  value  of  -1  and  the  options  argument  has  a  value  of  zero.  Other¬ 
wise,  its  behavior  shall  be  modified  by  the  values  of  the  pid  and  options 
arguments. 

The  pid  argument  specifies  a  set  of  child  processes  for  which  status  is  requested. 
The  waitpidi)  function  shall  only  return  the  status  of  a  child  process  from  this 
set. 

(1)  If  pid  is  equal  to  -1,  status  is  requested  for  any  child  process.  In  this 
respect,  waitpidi)  is  then  equivalent  to  waiti). 

(2)  If  pid  is  greater  than  zero,  it  specifies  the  process  ID  of  a  single  child  pro¬ 
cess  for  which  status  is  requested. 

(3)  If  pid  is  equal  to  zero,  status  is  requested  for  any  child  process  whose 
process  group  ID  is  equal  to  that  of  the  calling  process. 

(4)  If  pid  is  less  than  -1,  status  is  requested  for  any  child  process  whose  pro¬ 
cess  group  ID  is  equal  to  the  absolute  value  of  pid. 

The  options  argument  is  constructed  from  the  bitwise  inclusive  OR  of  zero  or  more 
of  the  following  flags,  defined  in  the  header  <sys/wait .  h>: 

WNOHANG  The  waitpid  ()  function  shall  not  suspend  execution  of  the  cal¬ 
ling  process  if  status  is  not  immediately  available  for  one  of  the 
child  processes  specified  by  pid. 

WUNTRACED  If  the  implementation  supports  job  control,  the  status  of  any 
child  processes  specified  by  pid  that  are  stopped,  and  whose 
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status  has  not  yet  been  reported  since  they  stopped,  shall  also 
be  reported  to  the  requesting  process. 

If  waitO  or  waitpidO  return  because  the  status  of  a  child  process  is  available, 
these  functions  shall  return  a  value  equal  to  the  process  ID  of  the  child  process. 
In  this  case,  if  the  value  of  the  argument  statJLoc  is  not  NULL,  information  shall 
be  stored  in  the  location  pointed  to  by  stat_loc .  If  and  only  if  the  status  returned 
is  from  a  terminated  child  process  that  returned  a  value  of  zero  from  mainO  or 
passed  a  value  of  zero  as  the  status  argument  to  _exit{ )  or  exit (),  the  value  stored 
at  the  location  pointed  to  by  stat_loc  shall  be  zero.  Regardless  of  its  value,  this 
information  may  be  interpreted  using  the  following  macros,  which  are  defined  in 
<sys/wait .  h>  and  evaluate  to  integral  expressions;  the  stat_val  argument  is  the 
integer  value  pointed  to  by  stat_loc . 

WlFEXITED(stat_val ) 

This  macro  evaluates  to  a  nonzero  value  if  status  was  returned 
for  a  child  process  that  terminated  normally. 

WEXLTSTATUS(stat_val ) 

If  the  value  of  WIFEXITED(s£a£_i;aZ )  is  nonzero,  this  macro 
evaluates  to  the  low-order  8  bits  of  the  status  argument  that 
the  child  process  passed  to  jexitO  or  exit( ),  or  the  value  the 
child  process  returned  from  main{). 

WIFSIGNALED(staM;a/ ) 

This  macro  evaluates  to  a  nonzero  value  if  status  was  returned 
for  a  child  process  that  terminated  due  to  the  receipt  of  a  signal 
that  was  not  caught  (see  3.3.1). 

WTERMSICXstaOaO 

If  the  value  of  WIFSIGNALED(sto£_i’a/ )  is  nonzero,  this  macro 
evaluates  to  the  number  of  the  signal  that  caused  the  termina¬ 
tion  of  the  child  process. 

WIFSTOPPED  (statjoal ) 

This  macro  evaluates  to  a  nonzero  value  if  status  was  returned 
for  a  child  process  that  is  currently  stopped. 

WSTOPSI  G(stat_val) 

If  the  value  of  WIFSTOPPED (statjual)  is  nonzero,  this  macro 
evaluates  to  the  number  of  the  signal  that  caused  the  child  pro¬ 
cess  to  stop. 

If  the  information  stored  at  the  location  pointed  to  by  stat_loc  was  stored  there  by 
a  call  to  the  waitpidO  function  that  specified  the  WUNTRACED  flag,  exactly 
one  of  the  macros  WIFEXITED(  *stat_loc),  WIFSIGNALEEK  *stat_loc),  or 
WIFSTOPPED(*sta£joc)  shall  evaluate  to  a  nonzero  value.  If  the  information 
stored  at  the  location  pointed  to  by  statjoc  was  stored  there  by  a  call  to  the  wait¬ 
pidO  function  that  did  not  specify  the  WUNTRACED  flag  or  by  a  call  to  the 
waitO  function,  exactly  one  of  the  macros  WIFEXITED(*sta£_/oc)  or 
WIFSIGNALEIX  *stat_loc)  shall  evaluate  to  a  nonzero  value. 
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An  implementation  may  define  additional  circumstances  under  which  waitO  or 
waitpid  ()  reports  status.  This  shall  not  occur  unless  the  calling  process  or  one  of 
its  child  processes  explicitly  makes  use  of  a  nonstandard  extension.  In  these 
cases,  the  interpretation  of  the  reported  status  is  implementation  defined. 


3.2.1.3  Returns 

If  the  waitO  or  waitpidO  functions  return  because  the  status  of  a  child  process  is 
available,  these  functions  shall  return  a  value  equal  to  the  process  ID  of  the  child 
process  for  which  status  is  reported.  If  the  waitO  or  waitpidO  functions  return 
due  to  the  delivery  of  a  signal  to  the  calling  process,  a  value  of  -1  shall  be 
returned  and  errno  shall  be  set  to  [EINTR].  If  the  waitpidO  function  was  invoked 
with  WNOHANG  set  in  options ,  has  at  least  one  child  process  specified  by  pid  for 
which  status  is  not  available,  and  status  is  not  available  for  any  process  specified 
by  pid,  a  value  of  zero  shall  be  returned.  Otherwise,  a  value  of  -1  shall  be 
returned,  and  errno  shall  be  set  to  indicate  the  error. 

3.2. 1.4  Errors 

If  any  of  the  following  conditions  occur,  the  wait{ )  function  shall  return  -1  and  set 
errno  to  the  corresponding  value: 

[ECHILD]  The  calling  process  has  no  existing  unwaited-for  child 
processes. 

[EINTR]  The  function  was  interrupted  by  a  signal.  The  value  of  the 

location  pointed  to  by  stat_loc  is  undefined. 

If  any  of  the  following  conditions  occur,  the  waitpidO  function  shall  return  -1  and 
set  errno  to  the  corresponding  value: 

[ECHILD]  The  process  or  process  group  specified  by  pid  does  not  exist  or 
is  not  a  child  of  the  calling  process. 

[EINTR]  The  function  was  interrupted  by  a  signal.  The  value  of  the 

location  pointed  to  by  statjoc  is  undefined. 

[EINVAL]  The  value  of  the  options  argument  is  not  valid. 

3.2.1.5  Cross-References 

jexitO,  3.2.2;  forkO,  3.1.1; pauseO,  3.4.2;  timesO,  4.5.2;  < signal .  h>,  3.3.1. 


3.2.2  Terminate  a  Process 

Function:  jexitO 
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3.2.2.1  Synopsis 

void  exit(int  status); 


3.2.2.2  Description 

The  _exit( )  function  shall  terminate  the  calling  process  with  the  following 

consequences: 

(1)  All  open  file  descriptors  and  directory  streams  in  the  calling  process  are 
closed. 

(2)  If  the  parent  process  of  the  calling  process  is  executing  a  wait()  or  wait- 
pid(),  it  is  notified  of  the  termination  of  the  calling  process  and  the  low 
order  8  bits  of  status  are  made  available  to  it;  see  3.2.1. 

(3)  If  the  parent  process  of  the  calling  process  is  not  executing  a  wait()  or 
waitpid()  function,  the  exit  status  code  is  saved  for  return  to  the  parent 
process  whenever  the  parent  process  executes  an  appropriate  subsequent 
wait{ )  or  waitpidi ). 

(4)  Termination  of  a  process  does  not  directly  terminate  its  children.  The 
sending  of  a  SIGHUP  signal  as  described  below  indirectly  terminates  chil¬ 
dren  in  some  circumstances.  Children  of  a  terminated  process  shall  be 
assigned  a  new  parent  process  ID,  corresponding  to  an  implementation- 
defined  system  process. 

(5)  If  the  implementation  supports  the  SIGCHLD  signal,  a  SIGCHLD  signal 
shall  be  sent  to  the  parent  process. 

(6)  If  the  process  is  a  controlling  process,  the  SIGHUP  signal  shall  be  sent  to 
each  process  in  the  foreground  process  group  of  the  controlling  terminal 
belonging  to  the  calling  process. 

(7)  If  the  process  is  a  controlling  process,  the  controlling  terminal  associated 
with  the  session  is  disassociated  from  the  session,  allowing  it  to  be 
acquired  by  a  new  controlling  process. 

(8)  If  the  implementation  supports  job  control,  and  if  the  exit  of  the  process 
causes  a  process  group  to  become  orphaned,  and  if  any  member  of  the 
newly  orphaned  process  group  is  stopped,  then  a  SIGHUP  signal  followed 
by  a  SIGCONT  signal  shall  be  sent  to  each  process  in  the  newly  orphaned 
process  group. 

These  consequences  shall  occur  on  process  termination  for  any  reason. 

3.2.2.3  Returns 

The  _exit( )  function  cannot  return  to  its  caller. 

3.2.2.4  Cross-References 

close (),  6.3.1;  sigactionO,  3.3.4;  wait ,  3.2.1. 
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3.3.1  Signal  Concepts 

3.3. 1.1  Signal  Names 

The  <signal .  h>  header  declares  the  sigsetjt  type  and  the  sigaction  structure.  It 
also  defines  the  following  symbolic  constants,  each  of  which  expands  to  a  distinct 
constant  expression  of  the  type  void(*)(),  whose  value  matches  no  declarable 
function. 


Symbolic 

Constant 

SIG_DFL 

SIGJGN 


Description 

Request  for  default  signal  handling 
Request  that  signal  be  ignored 


The  type  sigsetjt  is  used  to  represent  sets  of  signals.  It  is  always  an  integral  or 
structure  type.  Several  functions  used  to  manipulate  objects  of  type  sigsetjt  are 
defined  in  3.3.3. 

The  <signal  .h>  header  also  declares  the  constants  that  are  used  to  refer  to  the 
signals  that  occur  in  the  system.  Each  of  the  signals  defined  by  this  part  of 
ISO/IEC  9945  and  supported  by  the  implementation  shall  have  distinct,  positive 
integral  values.  The  value  zero  is  reserved  for  use  as  the  null  signal  (see  3.3.2). 
An  implementation  may  define  additional  signals  that  may  occur  in  the  system. 

The  constants  shown  in  Table  3-1  shall  be  supported  by  all  implementations. 

The  constants  shown  in  Table  3-2  shall  be  defined  by  all  implementations.  How¬ 
ever,  implementations  that  do  not  support  job  control  are  not  required  to  support 
these  signals.  If  these  signals  are  supported  by  the  implementation,  they  shall 
behave  in  accordance  with  this  part  of  ISO/IEC  9945.  Otherwise,  the  implementa¬ 
tion  shall  not  generate  these  signals,  and  attempts  to  send  these  signals  or  to 
examine  or  specify  their  actions  shall  return  an  error  condition.  See  3.3.2  and 
3.3.4. 


3.3.1.2  Signal  Generation  and  Delivery 

A  signal  is  said  to  be  generated  for  (or  sent  to)  a  process  when  the  event  that 
causes  the  signal  first  occurs.  Examples  of  such  events  include  detection  of 
hardware  faults,  timer  expiration,  and  terminal  activity,  as  well  as  the  invocation 
of  the  killi,)  function.  In  some  circumstances,  the  same  event  generates  signals 
for  multiple  processes. 

Each  process  has  an  action  to  be  taken  in  response  to  each  signal  defined  by  the 
system  (see  3.3. 1.3).  A  signal  is  said  to  be  delivered  to  a  process  when  the 
appropriate  action  for  the  process  and  signal  is  taken. 

During  the  time  between  the  generation  of  a  signal  and  its  delivery,  the  signal  is 
said  to  b spending.  Ordinarily,  this  interval  cannot  be  detected  by  an  application. 
However,  a  signal  can  be  blocked  from  delivery  to  a  process.  If  the  action  associ¬ 
ated  with  a  blocked  signal  is  anything  other  than  to  ignore  the  signal,  and  if  that 
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411  Table  3-1  -  Required  Signals 

412  .  .  . . 


413 

414 

Symbolic  Default  n  ... 

„  ,  ...  Description 

Constant  Action 

415 

SIGABRT 

l  Abnormal  termination  signal,  such  as  is  initiated  by  the  abortO  function 

416 

(as  defined  in  the  C  Standard  {2}). 

417 

SIGALRM 

l  Timeout  signal,  such  as  initiated  by  the  alarm()  function  (see  3.4.1). 

418 

SIGFPE 

l  Erroneous  arithmetic  operation,  such  as  division  by  zero  or  an  operation 

419 

resulting  in  overflow. 

420 

SIGHUP 

l  Hangup  detected  on  controlling  terminal  (see  7.1.1.10)  or  death  of  control- 

421 

ling  process  (see  3.2.2). 

422 

SIGILL 

l  Detection  of  an  invalid  hardware  instruction. 

423 

SIGINT 

l  Interactive  attention  signal  (see  7. 1.1.9). 

424 

SIGKILL 

l  Termination  signal  (cannot  be  caught  or  ignored). 

425 

SIGPIPE 

l  Write  on  a  pipe  with  no  readers  (see  6.4.2). 

426 

SIGQUIT 

l  Interactive  termination  signal  (see  7. 1.1.9). 

427 

SIGSEGV 

l  Detection  of  an  invalid  memory  reference. 

428 

SIGTERM 

l  Termination  signal. 

429 

SIGUSR1 

l  Reserved  as  application-defined  signal  1. 

430 

SIGUSR2 

l  Reserved  as  application-defined  signal  2. 

431 

432 

NOTE:  The  default  actions  are 

433 

l  Abnormal  termination  of  the  process. 

434 

435 

Table  3-2  -  Job  Control  Signals 

436 

437 

Symbolic 

Constant 

Default 

Action 

Description 

438 

SIGCHLD 

2 

Child  process  terminated  or  stopped. 

439 

SIGCONT 

4 

Continue  if  stopped. 

440 

SIGSTOP 

3 

Stop  signal  (cannot  be  caught  or  ignored). 

441 

SIGTSTP 

3 

Interactive  stop  signal  (see  7. 1.1.9). 

442 

443 

SIGTTIN 

3 

Read  from  control  terminal  attempted  by  a  member  of  a  background  pro¬ 
cess  group  (see  7. 1.1. 4). 

444 

445 

446 

SIGTTOU 

3 

Write  to  control  terminal  attempted  by  a  member  of  a  background  process 
group  (see  7. 1.1. 4). 

447  NOTE:  The  default  actions  are 

448  2  Ignore  the  signal. 

449  3  Stop  the  process. 

450  4  Continue  the  process  if  it  is  currently  stopped;  otherwise,  ignore  the  signal. 
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signal  is  generated  for  the  process,  the  signal  shall  remain  pending  until  either  it 
is  unblocked  or  the  action  associated  with  it  is  set  to  ignore  the  the  signal.  If  the 
action  associated  with  a  blocked  signal  is  to  ignore  the  signal,  and  if  that  signal  is 
generated  for  the  process,  it  is  unspecified  whether  the  signal  is  discarded 
immediately  upon  generation  or  remains  pending. 

Each  process  has  a  signal  mask  that  defines  the  set  of  signals  currently  blocked 
from  delivery  to  it.  The  signal  mask  for  a  process  is  initialized  from  that  of  its 
parent.  The  sigaction  (),  sigprocmask (),  and  sigsuspendO  functions  control  the 
manipulation  of  the  signal  mask. 

The  determination  of  which  action  is  taken  in  response  to  a  signal  is  made  at  the 
time  the  signal  is  delivered,  allowing  for  any  changes  since  the  time  of  generation. 
This  determination  is  independent  of  the  means  by  which  the  signal  was  origi¬ 
nally  generated.  If  a  subsequent  occurrence  of  a  pending  signal  is  generated,  it  is 
implementation  defined  as  to  whether  the  signal  is  delivered  more  than  once.  The 
order  in  which  multiple,  simultaneously  pending  signals  are  delivered  to  a  pro¬ 
cess  is  unspecified. 

When  any  stop  signal  (SIGSTOP,  SIGTSTP,  SIGTTIN,  SIGTTOU)  is  generated  for  a 
process,  any  pending  SIGCONT  signals  for  that  process  shall  be  discarded.  Con¬ 
versely,  when  SIGCONT  is  generated  for  a  process,  all  pending  stop  signals  for 
that  process  shall  be  discarded.  When  SIGCONT  is  generated  for  a  process  that  is 
stopped,  the  process  shall  be  continued,  even  if  the  SIGCONT  signal  is  blocked  or 
ignored.  If  SIGCONT  is  blocked  and  not  ignored,  it  shall  remain  pending  until  it  is 
either  unblocked  or  a  stop  signal  is  generated  for  the  process. 

An  implementation  shall  document  any  conditions  not  specified  by  this  part  of 
ISO/IEC  9945  under  which  the  implementation  generates  signals.  (See  1.3. 1.2.) 

3.3.1.3  Signal  Actions 

There  are  three  types  of  actions  that  can  be  associated  with  a  signal:  SIG_DFL, 
SIG_IGN,  or  a  pointer  to  a  function .  Initially,  all  signals  shall  be  set  to  SIG_DFL  or 
SIG_IGN  prior  to  entry  of  the  main{)  routine  (see  3.1.2).  The  actions  prescribed  by 
these  values  are  as  follows: 

(1)  SIG_DFL  —  signal-specific  default  action 

(a)  The  default  actions  for  the  signals  defined  in  this  part  of 
ISO/IEC  9945  are  specified  in  Table  3-1  and  Table  3-2. 

(b)  If  the  default  action  is  to  stop  the  process,  the  execution  of  that  pro¬ 
cess  is  temporarily  suspended.  When  a  process  stops,  a  SIGCHLD 
signal  shall  be  generated  for  its  parent  process,  unless  the  parent 
process  has  set  the  SA_NOCLDSTOP  flag  (see  3.3.4).  While  a  process 
is  stopped,  any  additional  signals  that  are  sent  to  the  process  shall 
not  be  delivered  until  the  process  is  continued  except  SIGKILL, 
which  always  terminates  the  receiving  process.  A  process  that  is  a 
member  of  an  orphaned  process  group  shall  not  be  allowed  to  stop 
in  response  to  the  SIGTSTP,  SIGTTIN,  or  SIGTTOU  signals.  In  cases 
where  delivery  of  one  of  these  signals  would  stop  such  a  process,  the 
signal  shall  be  discarded. 
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(c)  Setting  a  signal  action  to  SIG_DFL  for  a  signal  that  is  pending,  and 
whose  default  action  is  to  ignore  the  signal  (for  example,  SIGCHLD), 
shall  cause  the  pending  signal  to  be  discarded,  whether  or  not  it  is 
blocked. 

(2)  SIG_IGN  —  ignore  signal 

(a)  Delivery  of  the  signal  shall  have  no  effect  on  the  process.  The 
behavior  of  a  process  is  undefined  after  it  ignores  a  SIGFPE,  SIGILL, 
or  SIGSEGV  signal  that  was  not  generated  by  the  kill()  function  or 
the  raise ()  function  defined  by  the  C  Standard  {2}. 

(b)  The  system  shall  not  allow  the  action  for  the  signals  SIGKILL  or 
SIGSTOP  to  be  set  to  SIG.IGN. 

(c)  Setting  a  signal  action  to  SIG_IGN  for  a  signal  that  is  pending  shall 
cause  the  pending  signal  to  be  discarded,  whether  or  not  it  is 
blocked. 

(d)  If  a  process  sets  the  action  for  the  SIGCHLD  signal  to  SIG_IGN,  the 
behavior  is  unspecified. 

(3)  pointer  to  a  function  —  catch  signal 

(a)  On  delivery  of  the  signal,  the  receiving  process  is  to  execute  the 
signal-catching  function  at  the  specified  address.  After  returning 
from  the  signal-catching  function,  the  receiving  process  shall 
resume  execution  at  the  point  at  which  it  was  interrupted. 

(b)  The  signal-catching  function  shall  be  entered  as  a  C  language  func¬ 
tion  call  as  follows: 

void  func  (int  signo)  ; 

where  func  is  the  specified  signal-catching  function  and  signo  is  the 
signal  number  of  the  signal  being  delivered. 

(c)  The  behavior  of  a  process  is  undefined  after  it  returns  normally 
from  a  signal-catching  function  for  a  SIGFPE,  SIGILL,  or  SIGSEGV 
signal  that  was  not  generated  by  the  kill()  function  or  the  raise () 
function  defined  by  the  C  Standard  {2}. 

(d)  The  system  shall  not  allow  a  process  to  catch  the  signals  SIGKILL 
and  SIGSTOP. 

(e)  If  a  process  establishes  a  signal-catching  function  for  the  SIGCHLD 
signal  while  it  has  a  terminated  child  process  for  which  it  has  not 
waited,  it  is  unspecified  whether  a  SIGCHLD  signal  is  generated  to 
indicate  that  child  process. 

(f)  When  signal-catching  functions  are  invoked  asynchronously  with 
process  execution,  the  behavior  of  some  of  the  functions  defined  by 
this  part  of  ISO/IEC  9945  is  unspecified  if  they  are  called  from  a 
signal-catching  function.  The  following  table  defines  a  set  of  func¬ 
tions  that  shall  be  reentrant  with  respect  to  signals  (that  is,  appli¬ 
cations  may  invoke  them,  without  restriction,  from  signal-catching 
functions). 
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_exit() 

fstat() 

read  () 

sysconfi ) 

access () 

getegidO 

rename  () 

tcdrain  () 

alarm  () 

geteuidO 

rmdir{) 

tcflow  ( ) 

cfgetispeed{ ) 

getgidi) 

setgid{) 

tcflushO 

cfgetospeed{ ) 

getgroups  () 

setpgidi) 

tcgetattr{ ) 

cfsetispeedi ) 

getpgrp  () 

setsidO 

tcgetpgrpi) 

cfsetospeedi ) 

getpidi) 

setuidO 

tcsendbreaki) 

chdir{ ) 

getppidO 

sigactionO 

tcsetattr( ) 

chmodi) 

getuid() 

sigaddseti ) 

tcsetpgrpi) 

chowni) 

kill{) 

sigdelsetO 

time  () 

close () 

link  () 

sigemptysetO 

times  () 

creati) 

Iseek () 

sigfillseti ) 

umaskO 

dup2{) 

mkdir( ) 

sigismember{ ) 

uname() 

dup  () 

mkfifoO 

sigpendingi ) 

unlinkO 

execle  () 

open  () 

sigprocmask  () 

utimeO 

execveO 

pathconfi ) 

sigsuspend{) 

wait() 

fcntlO 

pause  () 

sleep  () 

waitpidO 

fork() 

pipe  () 

stat() 

write  () 

All  POSIX.1  functions  not  in  the  preceding  table  and  all  functions 
defined  in  the  C  Standard  {2}  not  stated  to  be  callable  from  a 
signal-catching  function  are  considered  to  be  unsafe  with  respect  to 
signals.  In  the  presence  of  signals,  all  functions  defined  by  this  part 
of  ISO/IEC  9945  or  by  the  C  Standard  {2}  shall  behave  as  defined  (by 
the  defining  standard)  when  called  from  or  interrupted  by  a  signal- 
catching  function,  with  a  single  exception:  when  a  signal  interrupts 
an  unsafe  function  and  the  signal-catching  function  calls  an  unsafe 
function,  the  behavior  is  undefined. 

3 .3. 1.4  Signal  Effects  on  Other  Functions 

Signals  affect  the  behavior  of  certain  functions  defined  by  this  part  of 
ISO/IEC  9945  if  delivered  to  a  process  while  it  is  executing  such  a  function.  If  the 
action  of  the  signal  is  to  terminate  the  process,  the  process  shall  be  terminated 
and  the  function  shall  not  return.  If  the  action  of  the  signal  is  to  stop  the  process, 
the  process  shall  stop  until  continued  or  terminated.  Generation  of  a  SIGCONT 
signal  for  the  process  causes  the  process  to  be  continued,  and  the  original  function 
shall  continue  at  the  point  where  the  process  was  stopped.  If  the  action  of  the  sig¬ 
nal  is  to  invoke  a  signal-catching  function,  the  signal-catching  function  shall  be 
invoked;  in  this  case,  the  original  function  is  said  to  be  interrupted  by  the  signal. 
If  the  signal-catching  function  executes  a  return,  the  behavior  of  the  interrupted 
function  shall  be  as  described  individually  for  that  function.  Signals  that  are 
ignored  shall  not  affect  the  behavior  of  any  function;  signals  that  are  blocked  shall 
not  affect  the  behavior  of  any  function  until  they  are  delivered. 
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579  3.3.2  Send  a  Signal  to  a  Process 

580  Function:  kill() 

581  3.3.2.1  Synopsis 

582  #include  <sys/types  . h> 

583  #include  <signal.h> 

584  int  kill(pid_t  pid,  int  sig)  ; 

585  3.3.2.2  Description 

586  The  kill()  function  shall  send  a  signal  to  a  process  or  a  group  of  processes 

587  specified  by  pid.  The  signal  to  be  sent  is  specified  by  sig  and  is  either  one  from 

588  the  list  given  in  3.3. 1.1  or  zero.  If  sig  is  zero  (the  null  signal),  error  checking  is  | 

589  performed,  but  no  signal  is  actually  sent.  The  null  signal  can  be  used  to  check  the 

590  validity  of  pid . 

591  For  a  process  to  have  permission  to  send  a  signal  to  a  process  designated  by  pid, 

592  the  real  or  effective  user  ID  of  the  sending  process  must  match  the  real  or  effective 

593  user  ID  of  the  receiving  process,  unless  the  sending  process  has  appropriate 

594  privileges.  If  {_POSIX_SAVED_IDS}  is  defined,  the  saved  set-user-ID  of  the  receiv- 

595  ing  process  shall  be  checked  in  place  of  its  effective  user  ID.  | 

596  If  pid  is  greater  than  zero,  sig  shall  be  sent  to  the  process  whose  process  ID  is 

597  equal  to  pid. 

598  If  pid  is  zero,  sig  shall  be  sent  to  all  processes  (excluding  an  unspecified  set  of  sys-  | 

599  tern  processes)  whose  process  group  ID  is  equal  to  the  process  group  ID  of  the 

600  sender  and  for  which  the  process  has  permission  to  send  a  signal. 

601  If  pid  is  -1,  the  behavior  of  the  kill( )  function  is  unspecified. 

602  If  pid  is  negative,  but  not  -1,  sig  shall  be  sent  to  all  processes  (excluding  an  | 

603  unspecified  set  of  system  processes)  whose  process  group  ID  is  equal  to  the  abso-  | 

604  lute  value  of  pid  and  for  which  the  process  has  permission  to  send  a  signal. 

605  If  the  value  of  pid  causes  sig  to  be  generated  for  the  sending  process,  and  if  sig  is 

606  not  blocked,  either  sig  or  at  least  one  pending  unblocked  signal  shall  be  delivered 

607  to  the  sending  process  before  the  kill()  function  returns. 

608  If  the  implementation  supports  the  SIGCONT  signal,  the  user  ID  tests  described 

609  above  shall  not  be  applied  when  sending  SIGCONT  to  a  process  that  is  a  member 

610  of  the  same  session  as  the  sending  process. 

611  An  implementation  that  provides  extended  security  controls  may  impose  further 

612  implementation- defined  restrictions  on  the  sending  of  signals,  including  the  null 

613  signal.  In  particular,  the  system  may  deny  the  existence  of  some  or  all  of  the 

614  processes  specified  by  pid. 

615  The  kill()  function  is  successful  if  the  process  has  permission  to  send  sig  to  any  of 

616  the  processes  specified  by  pid.  If  the  kill( )  function  fails,  no  signal  shall  be  sent. 
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617 

3.3.2.3  Returns 

618 

619 

Upon  successful  completion,  the  function  shall  return  a  value  of  zero.  Otherwise, 
a  value  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error. 

620 

3.3.2.4  Errors 

621 

622 

If  any  of  the  following  conditions  occur,  the  killO  function  shall  return  -1  and  set 
errno  to  the  corresponding  value: 

623 

624 

[EINVAL1 

The  value  of  the  sig  argument  is  an  invalid  or  unsupported  sig¬ 
nal  number. 

625 

626 

[EPERM] 

The  process  does  not  have  permission  to  send  the  signal  to  any 
receiving  process. 

627 

628 

[ESRCH] 

No  process  or  process  group  can  be  found  corresponding  to  that 
specified  by  pid. 

629  3.3.2.5  Cross-References 

630  getpidO,  4.1.1;  setsidO,  4.3.2;  sigactionO,  3.3.4;  <signal  .h>,  3.3.1. 


631  3.3.3  Manipulate  Signal  Sets 

632  Functions:  sigemptyseti ),  sigfillseti ),  sigaddset{ ),  sigdelseti ),  sigismember( ) 


633 

634 

635 

636 

637 

638 

639 


3.3.3.1  Synopsis 

♦include  <signal.h> 

int  sigemptyset  (sigset_t  *set)  ; 

int  sigf  illset  (sigset_t  *set)  ; 

int  sigaddset  (sigset__t  *set ,  int  signo)  ; 

int  sigdelset  (sigset_t  *set,  int  signo); 

int  sigismember  (const  sigset_t  *set,  int  signo); 


640  3.3.3.2  Description 

641  The  sigsetops  primitives  manipulate  sets  of  signals.  They  operate  on  data  objects 

642  addressable  by  the  application,  not  on  any  set  of  signals  known  to  the  system, 

643  such  as  the  set  blocked  from  delivery  to  a  process  or  the  set  pending  for  a  process 

644  (see  3.3.1). 

645  The  sigemptysetO  function  initializes  the  signal  set  pointed  to  by  the  argument 

646  set,  such  that  all  signals  defined  in  this  part  of  ISO/IEC  9945  are  excluded. 

647  The  sigfillsetO  function  initializes  the  signal  set  pointed  to  by  the  argument  set, 

648  such  that  all  signals  defined  in  this  part  of  ISO/IEC  9945  are  included. 

649  Applications  shall  call  either  sigemptysetO  or  sigfillsetO  at  least  once  for  each 

650  object  of  type  sigsetjt  prior  to  any  other  use  of  that  object.  If  such  an  object  is  not 
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651  initialized  in  this  way,  but  is  nonetheless  supplied  as  an  argument  to  any  of  the 

652  sigaddseti ),  sigdelseti ),  sigismemberi ),  sigactioni),  sigprocmaski),  sigpendingi ),  or 

653  sigsuspendO  functions,  the  results  are  undefined. 

654  The  sigaddset ()  and  sigdelset ()  functions  respectively  add  or  delete  the  individual 

655  signal  specified  by  the  value  of  the  argument  signo  to  or  from  the  signal  set 

656  pointed  to  by  the  argument  set. 

657  The  sigismemberi )  function  tests  whether  the  signal  specified  by  the  value  of  the 

658  argument  signo  is  a  member  of  the  set  pointed  to  by  the  argument  set. 

659  3. 3 .3.3  Returns 

660  Upon  successful  completion,  the  sigismemberi)  function  returns  a  value  of  one  if 

661  the  specified  signal  is  a  member  of  the  specified  set,  or  a  value  of  zero  if  it  is  not. 

662  Upon  successful  completion,  the  other  functions  return  a  value  of  zero.  For  all  of 

663  the  above  functions,  if  an  error  is  detected,  a  value  of-1  is  returned,  and  errno  is 

664  set  to  indicate  the  error. 

665  3.3.3.4  Errors 

666  For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  sigaddseti), 

667  sigdelseti),  and  sigismemberi)  functions  shall  return  -1  and  set  errno  to  the 

668  corresponding  value: 

669  [EINVAL]  The  value  of  the  signo  argument  is  an  invalid  or  unsupported 

670  signal  number. 

671  3.3.3.5  Cross-References 

672  sigaction{),  3.3.4;  <signal.h>,  3.3.1;  sigpendingi),  3.3.6;  sigprocmaski),  3.3.5; 

673  sigsuspendi),  3.3.7. 

674  3.3.4  Examine  and  Change  Signal  Action 

675  Function:  sigactioni) 

676  3.3.4.1  Synopsis 

677  #include  <signal.h> 

678  int  sigaction  ( int  sig,  const  struct  sigaction  *act , 

679  struct  sigaction  *OClCt)  ; 

680  3.3.4.2  Description 

681  The  sigactioni )  function  allows  the  calling  process  to  examine  or  specify  (or  both) 

682  the  action  to  be  associated  with  a  specific  signal.  The  argument  sig  specifies  the 

683  signal;  acceptable  values  are  defined  in  3. 3.1.1. 

684  The  structure  sigaction,  used  to  describe  an  action  to  be  taken,  is  defined  in  the 
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header  < signal .  h>  to  include  at  least  the  following  members: 


Member 

Type 

void  (*X) 
sigsetj 


Member 

Name 

sajiandler 

sajnask 


int  sa  Jlags 


Description 

SIG_DFL,  SIG_IGN,  or  pointer  to  a  function. 
Additional  set  of  signals  to  be  blocked  during 
execution  of  signal-catching  function. 

Special  flags  to  affect  behavior  of  signal. 


Implementations  may  add  extensions  as  permitted  in  1.3. 1.1,  point  (2).  Adding  | 
extensions  to  this  structure,  which  might  change  the  behavior  of  the  application  | 
with  respect  to  this  standard  when  those  fields  in  the  structure  are  uninitialized,  | 
also  requires  that  the  extensions  be  enabled  as  required  by  1.3. 1.1.  | 

If  the  argument  act  is  not  NULL,  it  points  to  a  structure  specifying  the  action  to 
be  associated  with  the  specified  signal.  If  the  argument  oact  is  not  NULL,  the 
action  previously  associated  with  the  signal  is  stored  in  the  location  pointed  to  by 
the  argument  oact.  If  the  argument  act  is  NULL,  signal  handling  is  unchanged  by 
this  function  call;  thus,  the  call  can  be  used  to  enquire  about  the  current  handling 
of  a  given  signal.  The  sajiandler  field  of  the  sigaction  structure  identifies  the 
action  to  be  associated  with  the  specified  signal.  If  the  sajiandler  field  specifies  a 
signal-catching  function,  the  sajnask  field  identifies  a  set  of  signals  that  shall  be 
added  to  the  signal  mask  of  the  process  before  the  signal-catching  function  is 
invoked.  The  SIGKILL  and  SIGSTOP  signals  shall  not  be  added  to  the  signal  mask 
using  this  mechanism;  this  restriction  shall  be  enforced  by  the  system  without 
causing  an  error  to  be  indicated. 

The  sa  Jlags  field  can  be  used  to  modify  the  behavior  of  the  specified  signal. 

The  following  flag  bit,  defined  in  the  header  <  signal .  h>,  can  be  set  in  sa  Jlags : 


Symbolic 

Constant 

SA_NOCLDSTOP 


Description 

Do  not  generate  SIGCHLD  when  children  stop. 


If  sig  is  SIGCHLD  and  the  SA_NOCLDSTOP  flag  is  not  set  in  sa  Jlags ,  and  the 
implementation  supports  the  SIGCHLD  signal,  a  SIGCHLD  signal  shall  be  gen¬ 
erated  for  the  calling  process  whenever  any  of  its  child  processes  stop.  If  sig  is 
SIGCHLD  and  the  SA_NOCLDSTOP  flag  is  set  in  sa  Jlags,  the  implementation 
shall  not  generate  a  SIGCHLD  signal  in  this  way. 

When  a  signal  is  caught  by  a  signal-catching  function  installed  by  the  sigactionO 
function,  a  new  signal  mask  is  calculated  and  installed  for  the  duration  of  the 
signal-catching  function  [or  until  a  call  to  either  the  sigprocmask  ()  or  sig- 
suspendi)  function  is  made].  This  mask  is  formed  by  taking  the  union  of  the 
current  signal  mask  and  the  value  of  the  sajnask  for  the  signal  being  delivered, 
and  then  including  the  signal  being  delivered.  If  and  when  the  user’s  signal 
handler  returns  normally,  the  original  signal  mask  is  restored. 

Once  an  action  is  installed  for  a  specific  signal,  it  remains  instated  until  another 
action  is  explicitly  requested  [by  another  call  to  the  sigactionO  function]  or  until 
one  of  the  exec  functions  is  called. 
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728  If  the  previous  action  for  sig  had  been  established  by  the  signalO  function, 

729  defined  in  the  C  Standard  {2},  the  values  of  the  fields  returned  in  the  structure 

730  pointed  to  by  oact  are  unspecified  and,  in  particular,  oact->sv Jiandler  is  not 

731  necessarily  the  same  value  passed  to  the  signalO  function.  However,  if  a  pointer 

732  to  the  same  structure  or  a  copy  thereof  is  passed  to  a  subsequent  call  to  the  sigac- 

733  tionO  function  via  the  act  argument,  handling  of  the  signal  shall  be  as  if  the  origi- 

734  nal  call  to  the  signali )  function  were  repeated. 

735  If  the  sigaction  ()  function  fails,  no  new  signal  handler  is  installed. 

736  It  is  unspecified  whether  an  attempt  to  set  the  action  for  a  signal  that  cannot  be  | 

737  caught  or  ignored  to  SIG_DFL  is  ignored  or  causes  an  error  to  be  returned  with  | 

738  errno  set  to  [EINVAL].  j 

739  3. 3.4.3  Returns 

740  Upon  successful  completion,  a  value  of  zero  is  returned.  Otherwise,  a  value  of  -1 

741  is  returned  and  errno  is  set  to  indicate  the  error. 

742  3.3.4.4  Errors 

743  If  any  of  the  following  conditions  occur,  the  sigactionO  function  shall  return  -1 

744  and  set  errno  to  the  corresponding  value: 

745  [EINVAL]  The  value  of  the  sig  argument  is  an  invalid  or  unsupported  sig- 

746  nal  number,  or  an  attempt  was  made  to  catch  a  signal  that  can- 

747  not  be  caught  or  to  ignore  a  signal  that  cannot  be  ignored.  See  | 

748  3.3. 1.1.  I 

749  For  each  of  the  following  conditions,  when  the  condition  is  detected  and  the  imple-  | 

750  mentation  treats  it  as  an  error,  the  sigactionO  function  shall  return  a  value  of-1  | 

751  and  set  errno  to  the  corresponding  value.  I 

752  [EINVAL]  An  attempt  was  made  to  set  the  action  to  SIG_DFL  for  a  signal  | 

753  that  cannot  be  caught  or  ignored  (or  both).  | 

754  3.3.4.5  Cross-References 

755  killO,  3.3.2;  <signal .  h>,  3.3.1;  sigprocmask (),  3.3.5;  sigsetops,  3.3.3;  sig- 

756  suspendO,  3.3.7. 

757  3.3.5  Examine  and  Change  Blocked  Signals 

758  Function:  sigprocmaskO 

759  3.3.5.1  Synopsis 

760  #include  <signal.h> 

761  int  sigprocmask  (int  how,  const  sigset_t  *set,  sigset_t  *oset)  ; 
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762  3.3.5.2  Description 


763  The  sigprocmaski)  function  is  used  to  examine  or  change  (or  both)  the  signal 

764  mask  of  the  calling  process.  If  the  value  of  the  argument  set  is  not  NULL,  it 

765  points  to  a  set  of  signals  to  be  used  to  change  the  currently  blocked  set. 


766  The  value  of  the  argument  how  indicates  the  manner  in  which  the  set  is  changed 

767  and  shall  consist  of  one  of  the  following  values,  as  defined  in  the  header 

768  <signal.h>: 


769 

770 

771 

772 

773 

774 

775 

776 


Name 

SIG_BLOCK 

SIG_UNBLOCK 

SIG_SETMASK 


_ Description _ _  _ 

The  resulting  set  shall  be  the  union  of  the  current  set  and 
the  signal  set  pointed  to  by  the  argument  set . 

The  resulting  set  shall  be  the  intersection  of  the  current  set 
and  the  complement  of  the  signal  set  pointed  to  by  the  argu¬ 
ment  set. 

The  resulting  set  shall  be  the  signal  set  pointed  to  by  the 
argument  set. 


in  If  the  argument  oset  is  not  NULL,  the  previous  mask  is  stored  in  the  space 

778  pointed  to  by  oset.  If  the  value  of  the  argument  set  is  NULL,  the  value  of  the 

779  argument  how  is  not  significant  and  the  signal  mask  of  the  process  is  unchanged 

780  by  this  function  call;  thus,  the  call  can  be  used  to  enquire  about  currently  blocked 

781  signals. 

782  If  there  are  any  pending  unblocked  signals  after  the  call  to  the  sigprocmaski) 

783  function,  at  least  one  of  those  signals  shall  be  delivered  before  the  sigprocmaski ) 

784  function  returns. 

785  It  is  not  possible  to  block  the  SIGKILL  and  SIGSTOP  signals;  this  shall  be  enforced 

786  by  the  system  without  causing  an  error  to  be  indicated. 

787  If  any  of  the  SIGFPE,  SIGILL,  or  SIGSEGV  signals  are  generated  while  they  are 

788  blocked,  the  result  is  undefined,  unless  the  signal  was  generated  by  a  call  to  the 

789  killi)  function  or  the  raisei )  function  defined  by  the  C  Standard  {2}. 

790  If  the  sigprocmaski)  function  fails,  the  signal  mask  of  the  process  is  not  changed 

791  by  this  function  call. 


792  3.3.5.3  Returns 

793  Upon  successful  completion  a  value  of  zero  is  returned.  Otherwise,  a  value  of  -1 

794  is  returned  and  errno  is  set  to  indicate  the  error. 

795  3.3.5.4  Errors 

796  If  any  of  the  following  conditions  occur,  the  sigprocmaski)  function  shall  return  -1 

797  and  set  errno  to  the  corresponding  value: 

798  [EINVALl  The  value  of  the  how  argument  is  not  equal  to  one  of  the 

799  defined  values. 
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r. 

T. 

7; 

7 

7 

7 

7 


800 

801 

802 

803 

804 

805 

806 
807 


3.3.5.5  Cross-References 

sigactioni),  3.3.4;  <signal  .h>,  3.3.1;  sigpending (),  3.3.6;  sigsetops,  3.3.3;  sig- 
suspendO,  3.3.7. 

3.3.6  Examine  Pending  Signals 

Function:  sigpending  ( ) 

3.3.6.1  Synopsis 

♦include  <signal.h> 

int  sigpending  (sigset_t  *set)  ; 


808  3.3.6.2  Description 

809  The  sigpending ()  function  shall  store  the  set  of  signals  that  are  blocked  from 

810  delivery  and  pending  for  the  calling  process  in  the  space  pointed  to  by  the  argu- 

811  mentse/. 


812  3.3.6.3  Returns 

813  Upon  successful  completion,  a  value  of  zero  is  returned.  Otherwise,  a  value  of  -1 

814  is  returned  and  errno  is  set  to  indicate  the  error. 


815  3.3.6.4  Errors 

816  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

817  to  be  detected  for  the  sigpending ()  function.  Some  errors  may  be  detected  under  | 

818  conditions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  | 

819  3. 3 .6.5  Cross-References 

820  <signal  .h>,  3.3.1;  sigprocmaskO,  3.3.5;  sigsetops,  3.3.3. 


821  3.3.7  Wait  for  a  Signal 

822  Function:  sigsuspendi ) 

823  3.3.7.1  Synopsis 

824  #include  <signal.h> 

825  int  sigsuspend  (const  sigset_t  *sigmask)  ; 
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826  3.S.7.2  Description 

827  The  sigsuspendi)  function  replaces  the  signal  mask  of  the  process  with  the  set  of 

828  signals  pointed  to  by  the  argument  sigmask  and  then  suspends  the  process  until 

829  delivery  of  a  signal  whose  action  is  either  to  execute  a  signal-catching  function  or 

830  to  terminate  the  process. 

831  If  the  action  is  to  terminate  the  process,  the  sigsuspendi )  function  shall  not 

832  return.  If  the  action  is  to  execute  a  signal-catching  function,  the  sigsuspendi ) 

833  shall  return  after  the  signal-catching  function  returns,  with  the  signal  mask 

834  restored  to  the  set  that  existed  prior  to  the  sigsuspendi )  call. 

835  It  is  not  possible  to  block  those  signals  that  cannot  be  ignored,  as  documented  in 

836  3.3.1;  this  shall  be  enforced  by  the  system  without  causing  an  error  to  be 

837  indicated. 

838  3.3.7.3  Returns 

839  Since  the  sigsuspendi )  function  suspends  process  execution  indefinitely,  there  is 

840  no  successful  completion  return  value.  A  value  of  -1  is  returned  and  errno  is  set 

841  to  indicate  the  error. 

842  3.3.7.4  Errors 

843  If  any  of  the  following  conditions  occur,  the  sigsuspendi )  function  shall  return  -1 

844  and  set  errno  to  the  corresponding  value: 

845  [EINTR]  A  signal  is  caught  by  the  calling  process,  and  control  is 

846  returned  from  the  signal-catching  function. 

847  3.3.7.5  Cross-References 

848  pause (),  3.4.2;  sigactioni ),  3.3.4;  <signal  .h>,  3.3.1;  sigpendingi ),  3.3.6;  sigproc- 

849  mas ki),  3.3.5;  sigsetops,  3.3.3. 


850  3.4  Timer  Operations 

851  A  process  can  suspend  itself  for  a  specific  period  of  time  with  the  sleep i)  function 

852  or  suspend  itself  indefinitely  with  the  pause  ()  function  until  a  signal  arrives.  The 

853  alarmi )  function  schedules  a  signal  to  arrive  at  a  specific  time,  so  a  pause () 

854  suspension  need  not  be  indefinite. 

855  3.4.1  Schedule  Alarm 

856  Function:  alarmi) 
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857  3.4.1. 1  Synopsis 

858  unsigned  int  alarm  (unsigned  int  seconds); 

859  3.4.1.2  Description 

860  The  alarm  ()  function  shall  cause  the  system  to  send  the  calling  process  a 

861  SIGALRM  signal  after  the  number  of  real-time  seconds  specified  by  seconds  have 

862  elapsed. 

863  Processor  scheduling  delays  may  cause  the  process  actually  not  to  begin  handling 

864  the  signal  until  after  the  desired  time. 

865  Alarm  requests  are  not  stacked;  only  one  SIGALRM  generation  can  be  scheduled 

866  in  this  manner.  If  the  SIGALRM  has  not  yet  been  generated,  the  call  will  result  in 

867  rescheduling  the  time  at  which  the  SIGALRM  will  be  generated. 

868  If  seconds  is  zero,  any  previously  made  alarm  ()  request  is  canceled. 

869  3.4.1.3  Returns 

870  If  there  is  a  previous  alarm ()  request  with  time  remaining,  the  alarmO  function  | 

871  shall  return  a  nonzero  value  that  is  the  number  of  seconds  until  the  previous  | 

872  request  would  have  generated  a  SIGALRM  signal.  Otherwise,  the  alarm  ()  func-  | 

873  tion  shall  return  zero. 

874  3.4.1.4  Errors 

875  The  alarm{)  function  is  always  successful,  and  no  return  value  is  reserved  to  indi- 

876  cate  an  error. 

877  3.4.1.5  Cross-References 

878  exec,  3.1.2;  fork(),  3.1.1; pause (),  3.4.2;  sigactioni),  3.3.4;  <signal .  h>,  3.3.1. 

879  3.4.2  Suspend  Process  Execution 

880  Function:  pause  () 

881  3.4.2.1  Synopsis 

882  int  pause  (void)  ; 

883  3.4.2.2  Description 

884  The  pause ()  function  suspends  the  calling  process  until  delivery  of  a  signal  whose 

885  action  is  either  to  execute  a  signal-catching  function  or  to  terminate  the  process. 

886  If  the  action  is  to  terminate  the  process,  the  pause  ( )  function  shall  not  return. 

887  If  the  action  is  to  execute  a  signal-catching  function,  the  pause  ()  function  shall 

888  return  after  the  signal-catching  function  returns. 


64 


3  Process  Primitives 


Part  1:  SYSTEM  API  [C  LANGUAGE] 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


889  3.4.2.3  Returns 

890  Since  the  pause{)  function  suspends  process  execution  indefinitely,  there  is  no 

891  successful  completion  return  value.  A  value  of  —1  is  returned  and  errno  is  set  to 

892  indicate  the  error. 

893  3.4.2.4  Errors 

894  If  any  of  the  following  conditions  occur,  the  paused)  function  shall  return  -1  and 

895  set  errno  to  the  corresponding  value: 

896  [EINTR]  A  signal  is  caught  by  the  calling  process,  and  control  is 

897  returned  from  the  signal-catching  function. 

898  3.4.2.5  Cross-References 

899  alarmi),  3.4.1;  kill(),  3.3.2;  wait ,  3.2.1;  3.3. 1.4. 

900  3.4.3  Delay  Process  Execution 

901  Function:  sleep  () 

902  3.4.3.1  Synopsis 

903  unsigned  int  sleep  (unsigned  int  seconds); 

904  3.4.3.2  Description 

905  The  sleep ()  function  shall  cause  the  current  process  to  be  suspended  from  execu- 

906  tion  until  either  the  number  of  real-time  seconds  specified  by  the  argument 

907  seconds  have  elapsed  or  a  signal  is  delivered  to  the  calling  process  and  its  action 

908  is  to  invoke  a  signal-catching  function  or  to  terminate  the  process.  The  suspen- 

909  sion  time  may  be  longer  than  requested  due  to  the  scheduling  of  other  activity  by 

910  the  system. 

911  If  a  SIGALRM  signal  is  generated  for  the  calling  process  during  execution  of  the 

912  sleep ()  function  and  the  SIGALRM  signal  is  being  ignored  or  blocked  from  delivery, 

913  it  is  unspecified  whether  sleep  ()  returns  when  the  SIGALRM  signal  is  scheduled. 

914  If  the  signal  is  being  blocked,  it  is  also  unspecified  whether  it  remains  pending 

915  after  the  sleep  ( )  function  returns  or  is  discarded. 

916  If  a  SIGALRM  signal  is  generated  for  the  calling  process  during  execution  of  the 

917  sleep  ()  function,  except  as  a  result  of  a  prior  call  to  the  alarm  ()  function,  and  if 

918  the  SIGALRM  signal  is  not  being  ignored  or  blocked  from  delivery,  it  is  unspecified 

919  whether  that  signal  has  any  effect  other  than  causing  the  sleep  ()  function  to 

920  return. 

921  If  a  signal-catching  function  interrupts  the  sleep  ()  function  and  either  examines 

922  or  changes  the  time  a  SIGALRM  is  scheduled  to  be  generated,  the  action  associ- 

923  ated  with  the  SIGALRM  signal,  or  whether  the  SIGALRM  signal  is  blocked  from 

924  delivery,  the  results  are  unspecified. 
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925  If  a  signal -catching  function  interrupts  the  sleep  0  function  and  calls  the 

926  siglongjmp ()  or  longjmp  ()  function  to  restore  an  environment  saved  prior  to  the 

927  sleepO  call,  the  action  associated  with  the  SIGALRM  signal  and  the  time  at  which 

928  a  SIGALRM  signal  is  scheduled  to  be  generated  are  unspecified.  It  is  also 

929  unspecified  whether  the  SIGALRM  signal  is  blocked,  unless  the  process’s  signal 

930  mask  is  restored  as  part  of  the  environment  (see  8.3.1). 

931  3.4.3.3  Returns 

932  If  the  sleep ()  function  returns  because  the  requested  time  has  elapsed,  the  value 

933  returned  shall  be  zero.  If  the  sleep ()  function  returns  due  to  delivery  of  a  signal, 

934  the  value  returned  shall  be  the  unslept  amount  (the  requested  time  minus  the 

935  time  actually  slept)  in  seconds. 

936  3.4.3.4  Errors 

937  The  sleep ()  function  is  always  successful,  and  no  return  value  is  reserved  to  indi- 

938  cate  an  error. 

939  3.4.3.5  Cross-References 

940  alarmO,  3.4.1; pause (),  3.4.2;  sigactioni) ,  3.3.4. 


66 


3  Process  Primitives 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


Section  4:  Process  Environment 

1  4.1  Process  Identification 

2  4.1.1  Get  Process  and  Parent  Process  IDs 

3  Functions:  getpidi),  getppidi) 

8  4.1. 1.2  Description 

9  The  getpidi)  function  returns  the  process  ID  of  the  calling  process. 

10  The  getppidi)  function  returns  the  parent  process  ID  of  the  calling  process. 

n  4.1. 1.3  Returns 

12  See  4. 1.1.2. 

13  4.1. 1.4  Errors 

14  The  getpidi)  axv& getppidi)  functions  are  always  successful,  and  no  return  value  is 

15  reserved  to  indicate  an  error. 

16  4.1. 1.5  Cross-References 

17  exec ,  3.1.2;  forki),  3.1.1;  killi),  3.3.2. 


4  4.1. 1.1  Synopsis 

5  #include  <sys/types . h> 

6  pid_t  getpid (void) ; 

7  pid_t  getppid ( void) ; 
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4.2  User  Identification 

4.2.1  Get  Real  User,  Effective  User,  Real  Group,  and  Effective  Group  IDs 

Functions:  getuidi ),  geteuid( ),  getgid{ ),  getegidi ) 

4.2.1. 1  Synopsis 

#include  <sys/types .h> 
uid_t  getuid ( void) ; 
uid_t  geteuid ( void) ; 
gid_t  getgid ( void) ; 
gid_t  getegid ( void)  ; 

4.2.1.2  Description 

The  getuidO  function  returns  the  real  user  ID  of  the  calling  process. 

The  geteuidO  function  returns  the  effective  user  ID  of  the  calling  process. 

The  getgidi )  function  returns  the  real  group  ID  of  the  calling  process. 

The  getegidO  function  returns  the  effective  group  ID  of  the  calling  process. 

4.2. 1.3  Returns 

See  4.2. 1.2. 

4.2.1.4  Errors 

The  getuidO,  geteuidO,  getgidO,  and  getegidO  functions  are  always  successful, 
and  no  return  value  is  reserved  to  indicate  an  error. 

4.2. 1.5  Cross-References 

setuidO,  4.2.2. 

4.2.2  Set  User  and  Group  IDs 

Functions:  setuidO,  setgidO 

4.2.2.1  Synopsis 

♦include  <sys/types . h> 
int  setuid(uid_t  uid)  ; 
int  setgid  (gid_t  gid)  ; 
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4.2.2.2  Description 

If  {_POSIX_SAVED_IDS}  is  defined: 

(1)  If  the  process  has  appropriate  privileges,  the  setuidO  function  sets  the 
real  user  ID,  effective  user  ID,  and  the  saved  set-user-ID  to  uid. 

(2)  If  the  process  does  not  have  appropriate  privileges,  but  uid  is  equal  to  the 
real  user  ID  or  the  saved  set-user-ID,  the  setuidO  function  sets  the  effec¬ 
tive  user  ID  to  uid;  the  real  user  ID  and  saved  set-user-ID  remain 
unchanged  by  this  function  call. 

(3)  If  the  process  has  appropriate  privileges,  the  setgidO  function  sets  the 
real  group  ID,  effective  group  ID,  and  the  saved  set-group-ID  to  gid. 

(4)  If  the  process  does  not  have  appropriate  privileges,  but  gid  is  equal  to  the 
real  group  ID  or  the  saved  set-group-ID,  the  setgidO  function  sets  the 
effective  group  ID  to  gid ;  the  real  group  ID  and  saved  set-group-ID  remain 
unchanged  by  this  function  call. 

Otherwise: 

(1)  If  the  process  has  appropriate  privileges,  the  setuidO  function  sets  the 
real  user  ID  and  effective  user  ID  to  uid. 

(2)  If  the  process  does  not  have  appropriate  privileges,  but  uid  is  equal  to  the 
real  user  ID,  the  setuidO  function  sets  the  effective  user  ID  to  uid;  the 
real  user  ID  remains  unchanged  by  this  function  call. 

(3)  If  the  process  has  appropriate  privileges,  the  setgidO  function  sets  the 
real  group  ID  and  effective  group  ID  to  gid. 

(4)  If  the  process  does  not  have  appropriate  privileges,  but  gid  is  equal  to  the 
real  group  ID,  the  setgidO  function  sets  the  effective  group  ID  to  gid;  the 
real  group  ID  remains  unchanged  by  this  function  call. 

Any  supplementary  group  IDs  of  the  calling  process  remain  unchanged  by  these 

function  calls. 

4.2.2.3  Returns 

Upon  successful  completion,  a  value  of  zero  is  returned.  Otherwise,  a  value  of  — 1 

is  returned  and  errno  is  set  to  indicate  the  error. 

4.2.2.4  Errors 

If  any  of  the  following  conditions  occur,  the  setuidO  function  shall  return  -1  and 

set  errno  to  the  corresponding  value: 

[EINVAL]  The  value  of  the  uid  argument  is  invalid  and  not  supported  by 
the  implementation. 

[EPERM]  The  process  does  not  have  appropriate  privileges  and  uid  does 
not  match  the  real  user  ID  or,  if  {_POSIX_SAVED_IDS}  is 
defined,  the  saved  set-user-ID. 
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83  If  any  of  the  following  conditions  occur,  the  setgidO  function  shall  return  -1  and 

84  set  errno  to  the  corresponding  value: 


85  [EINVAL]  The  value  of  the  gid  argument  is  invalid  and  not  supported  by 

86  the  implementation. 


87 

88 
89 


[EPERM]  The  process  does  not  have  appropriate  privileges  and  gid  does 
not  match  the  real  group  ID  or,  if  {_POSIX_SAVED_IDS}  is 
defined,  the  saved  set-group-ID. 


90  4.2.2.5  Cross-References 

91  exec,  3.1.2;  getuidO,  4.2.1. 


92  4.2.3  Get  Supplementary  Group  IDs 

93  Function:  getgroups () 

94  4.2.3. 1  Synopsis 

95  #include  <sys/types . h> 

96  int  getgroups  (int  gidsetsize ,  gid_t  grouplist  [  ] )  ; 

97  4.2.3.2  Description 

98  The  getgroups ()  function  fills  in  the  array  grouplist  with  the  supplementary  group  | 

99  IDs  of  the  calling  process.  The  gidsetsize  argument  specifies  the  number  of  ele-  | 

100  ments  in  the  supplied  array  grouplist.  The  actual  number  of  supplementary  | 

101  group  IDs  stored  in  the  array  is  returned.  The  values  of  array  entries  with  indices  | 

102  larger  than  or  equal  to  the  returned  value  are  undefined.  | 

103  As  a  special  case,  if  the  gidsetsize  argument  is  zero,  getgroups ()  returns  the 

104  number  of  supplemental  group  IDs  associated  with  the  calling  process  without 

105  modifying  the  array  pointed  to  by  the  grouplist  argument. 

106  4.2.3.3  Returns 

107  Upon  successful  completion,  the  number  of  supplementary  group  IDs  is  returned. 

108  This  value  is  zero  if  {NGROUPS_MAX}  is  zero.  A  return  value  of  -1  indicates 

109  failure,  and  errno  is  set  to  indicate  the  error. 

no  4.2.3.4  Errors 

in  If  any  of  the  following  conditions  occur,  the  getgroups ()  function  shall  return  -1 

112  and  set  errno  to  the  corresponding  value: 

113  [EINVAL]  The  gidsetsize  argument  is  not  equal  to  zero  and  is  less  than 

114  the  number  of  supplementary  group  IDs. 
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115  4.2.3.5  Cross-References 

lie  setgidO,  4.2.2. 


ii7  4.2.4  Get  User  Name 

us  Functions:  getloginO  | 

U9  4.2.4.1  Synopsis 

120  char  *get login  (void)  ; 

121  4.2.4.2  Description 

122  The  getloginO  function  returns  a  pointer  to  a  string  giving  a  user  name  associated  | 

123  with  the  calling  process,  which  is  the  login  name  associated  with  the  calling  | 

124  process.  | 

125  It  getloginO  returns  a  non-NULL  pointer,  that  pointer  points  to  the  name  under 

126  which  the  user  logged  in,  even  if  there  are  several  login  names  with  the  same 

127  user  ID. 

128  | 

129  4.2.4.3  Returns 

130  The  getloginO  function  returns  a  pointer  to  a  string  containing  the  user’s  login 

131  name,  or  a  NULL  pointer  if  the  user’s  login  name  cannot  be  found. 

132  The  return  value  from  getloginO  may  point  to  static  data  and,  therefore,  may  be 

133  overwritten  by  each  call. 

134  | 

135  4.2.4.4  Errors 

136  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

137  to  be  detected  for  the  getloginO  function.  Some  errors  may  be  detected  under  con-  | 

138  ditions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  | 

139  4.2.4.5  Cross-References 

140  getpwnamO,  9.2.2; getpwuidO,  9.2.2. 
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141  4.3  Process  Groups 

142  4.3.1  Get  Process  Group  ED 

143  Function:  getpgrp  () 

144  4.3.1. 1  Synopsis 

145  #include  <sys/types  . h> 

146  pid_t  getpgrp (void) ; 

147  4.3.1.2  Description 

148  The  getpgrp  ( )  function  returns  the  process  group  ID  of  the  calling  process. 

149  4.3. 1.3  Returns 

150  See  4.3. 1.2. 

151  4.3. 1.4  Errors 

152  The  getpgrp  ()  function  is  always  successful,  and  no  return  value  is  reserved  to 

153  indicate  an  error. 

154  4.3. 1.5  Cross-References 

155  setpgidi),  4.3.3;  setsidi),  4.3.2;  sigactioni),  3.3.4. 

156  4.3.2  Create  Session  and  Set  Process  Group  ID 

157  Function:  setsidi ) 

158  4.3.2. 1  Synopsis 

159  #include  <sys/types  . h> 

160  pid_t  set sid (void)  ; 

161  4.3.2.2  Description 

162  If  the  calling  process  is  not  a  process  group  leader,  the  setsidi)  function  shall 

163  create  a  new  session.  The  calling  process  shall  be  the  session  leader  of  this  new 

164  session,  shall  be  the  process  group  leader  of  a  new  process  group,  and  shall  have 

165  no  controlling  terminal.  The  process  group  ID  of  the  calling  process  shall  be  set 

166  equal  to  the  process  ID  of  the  calling  process.  The  calling  process  shall  be  the  only 

167  process  in  the  new  process  group  and  the  only  process  in  the  new  session. 
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168  4.S.2.S  Returns 

169  Upon  successful  completion,  the  setsidO  function  returns  the  value  of  the  process 

170  group  ID  of  the  calling  process.  Otherwise,  a  value  of  -1  is  returned  and  errno  is 

171  set  to  indicate  the  error. 

172  4.3.2.4  Errors 

173  If  any  of  the  following  conditions  occur,  the  setsidO  function  shall  return  -1  and 

174  set  errno  to  the  corresponding  value: 

175  [EPERM]  The  calling  process  is  already  a  process  group  leader,  or  the 

176  process  group  ID  of  a  process  other  than  the  calling  process 

177  matches  the  process  ID  of  the  calling  process. 

178  4.3.2.5  Cross-References 

179  exec,  3.1.2;  _exitO,  3.2.2;  forkO,  3.1.1;  getpidO,  4.1.1;  killO,  3.3.2;  setpgidO,  4.3.3; 

180  sigactionO,  3.3.4. 

181  4.3.3  Set  Process  Group  ID  for  Job  Control 

182  Function:  setpgidO 

183  4.3.3.1  Synopsis 

184  #include  <sys/types  .  h> 

185  int  setpgid  (pid_t  pid,  pid_t  pgid)  ; 

186  4.3.3.2  Description 

187  If  {_POSIX_JOB_CONTROL}  is  defined: 

188  The  setpgidO  function  is  used  to  either  join  an  existing  process  group  or 

189  create  a  new  process  group  within  the  session  of  the  calling  process.  The 

190  process  group  ID  of  a  session  leader  shall  not  change.  Upon  successful  com- 

191  pletion,  the  process  group  ID  of  the  process  with  a  process  ID  that  matches 

192  pid  shall  be  set  to  pgid.  As  a  special  case,  if  pid  is  zero,  the  process  ID  of 

193  the  calling  process  shall  be  used.  Also,  if  pgid  is  zero,  the  process  ID  of  the 

194  indicated  process  shall  be  used. 

195  Otherwise: 

196  Either  the  implementation  shall  support  the  setpgidO  function  as  described 

197  above  or  the  setpgidO  function  shall  fail. 

198  4.3.3.3  Returns 

199  Upon  successful  completion,  the  setpgidO  function  returns  a  value  of  zero.  Other- 

200  wise,  a  value  of -1  is  returned  and  errno  is  set  to  indicate  the  error. 
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201  4.3.3.4  Errors 


202  If  any  of  the  following  conditions  occur,  the  setpgidO  function  shall  return  -1  and 

203  set  errno  to  the  corresponding  value: 


204 

205 

206 


[EACCES]  The  value  of  the  pid  argument  matches  the  process  ID  of  a  child 
process  of  the  calling  process,  and  the  child  process  has  success¬ 
fully  executed  one  of  the  exec  functions. 


207 

208 

209 

210 


[EINVAL]  The  value  of  the  pgid  argument  is  less  than  zero  or  is  not  a 
value  supported  by  the  implementation. 

[ENOSYS]  The  setpgidi )  function  is  not  supported  by  this  implementation. 

[EPERM]  The  process  indicated  by  the  pid  argument  is  a  session  leader. 


211 

212 

213 


The  value  of  the  pid  argument  is  valid,  but  matches  the  process 
ID  of  a  child  process  of  the  calling  process,  and  the  child  process 
is  not  in  the  same  session  as  the  calling  process. 


214 

215 

216 
217 


The  value  of  the  pgid  argument  does  not  match  the  process  ID 
of  the  process  indicated  by  the  pid  argument,  and  there  is  no 
process  with  a  process  group  ID  that  matches  the  value  of  the 
pgid  argument  in  the  same  session  as  the  calling  process. 


218  [ESRCH]  The  value  of  the  pid  argument  does  not  match  the  process  ID  of 

219  the  calling  process  or  of  a  child  process  of  the  calling  process. 


220  4.3.3.5  Cross-References 

221  getpgrp (),  4.3.1;  setsidO,  4.3.2;  tcsetpgrp (),  7.2.4;  exec,  3.1.2. 


222  4.4  System  Identification 

223  4.4.1  Get  System  Name 

224  Function:  uname () 

225  4.4.1. 1  Synopsis 

226  #include  <sys/utsname  . h> 

227  int  uname  (struct  utsname  *name)  ; 

228  4.4.1.2  Description 

229  The  uname ()  function  stores  information  identifying  the  current  operating  system 

230  in  the  structure  pointed  to  by  the  argument  name . 

231  The  structure  utsname  is  defined  in  the  header  <sys/utsname  .  h>  and  contains 

232  at  least  the  members  shown  in  Table  4-1. 
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233  Table  4-1  -  uname  ()  Structure  Members 

234  _ _ 


235 

236 

Member 

Name 

Description 

237 

sysname 

Name  of  this  implementation  of  the  operating  system. 

238 

nodename 

Name  of  this  node  within  an  implementation-specified  communications  network. 

239 

release 

Current  release  level  of  this  implementation. 

240 

version 

Current  version  level  of  this  release. 

241 

machine 

Name  of  the  hardware  type  on  which  the  system  is  running. 

242 

243  Each  of  these  data  items  is  a  null-terminated  array  of  char. 

244  The  format  of  each  member  is  implementation  defined.  The  system  documenta- 

245  tion  (see  1.3. 1.2)  shall  specify  the  source  and  format  of  each  member  and  may 

246  specify  the  range  of  values  for  each  member. 

247  The  inclusion  of  the  nodename  member  in  this  structure  does  not  imply  that  it  is 

248  sufficient  information  for  interfacing  to  communications  networks. 

249  4.4. 1.3  Returns 

250  Upon  successful  completion,  a  nonnegative  value  is  returned.  Otherwise,  a  value 

251  of  -1  is  returned  and  errno  is  set  to  indicate  the  error. 

252  4.4.1.4  Errors 

253  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

254  to  be  detected  for  the  uname  ()  function.  Some  errors  may  be  detected  under  con- 

255  ditions  that  are  unspecified  by  this  part  of  ISO/IEC  9945. 


256  4.5  Time 

257  4.5.1  Get  System  Time 

258  Function:  timei) 

259  4.5.1. 1  Synopsis 

260  #include  <time.h> 

261  time_t  time  (time  t  *tloc)  ; 
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262  4.5.1.2  Description 

263  The  time{ )  function  returns  the  value  of  time  in  seconds  since  the  Epoch. 

264  The  argument  tloc  points  to  an  area  where  the  return  value  is  also  stored.  If  tloc 

265  is  a  NULL  pointer,  no  value  is  stored. 

266  4.5.1.3  Returns 

267  Upon  successful  completion,  time()  returns  the  value  of  time.  Otherwise,  a  value 

268  of  (( timejt )  -1)  is  returned  and  errno  is  set  to  indicate  the  error. 

269  4.5.1.4  Errors 

270  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

271  to  be  detected  for  the  time ()  function.  Some  errors  may  be  detected  under  condi-  | 

272  tions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  | 

273  4.5.2  Get  Process  Times 

274  Function:  times () 

275  4.5.2.1  Synopsis 


276  #include  <sys/times  .  h> 


277 

clock_t  times (struct  tms 

*buffer)  ; 

278 

4. 5.2.2  Description 

279 

The  times () 

function  shall 

fill  the  structure  pointed  to  by  buffer  with  time- 

280 

accounting  information.  The  type  clockjt  and  the  tms  structure  are  defined  in 

281 

<sys/times 

.  h>;  the  tms  structure  shall  contain  at  least  the  following  members: 

282 

Member 

Member 

Description 

283 

Type 

Name 

284 

clockjt 

tmsjutime 

User  CPU  time. 

285 

clock J 

tmsjstime 

System  CPU  time. 

286 

clock  J 

tms_cutime 

User  CPU  time  of  terminated  child  processes. 

287 

clock_t 

tmsjcstime 

System  CPU  time  of  terminated  child  processes. 

288  All  times  are  measured  in  terms  of  the  number  of  clock  ticks  used. 

289  The  times  of  a  terminated  child  process  are  included  in  the  tms_cutime  and 

290  tms_cstime  elements  of  the  parent  when  a  wait()  or  waitpid ()  function  returns  the 

291  process  ID  of  this  terminated  child.  See  3.2.1.  If  a  child  process  has  not  waited 

292  for  its  terminated  children,  their  times  shall  not  be  included  in  its  times. 

293  The  value  tmsjutime  is  the  CPU  time  charged  for  the  execution  of  user 

294  instructions. 
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295  The  value  tms_stime  is  the  CPU  time  charged  for  execution  by  the  system  on 

296  behalf  of  the  process. 

297  The  value  tmsjcutime  is  the  sum  of  the  tmsjitime s  and  tms_cutime s  of  the  child 

298  processes. 

299  The  value  tmsjcstime  is  the  sum  of  the  tms_stime  s  and  tmsjcstime  s  of  the  child 

300  processes. 

301  4.5.2.3  Returns 

302  Upon  successful  completion,  times ()  shall  return  the  elapsed  real  time,  in  clock  | 

303  ticks,  since  an  arbitrary  point  in  the  past  (for  example,  system  start-up  time). 

304  This  point  does  not  change  from  one  invocation  of  times ()  within  the  process  to 

305  another.  The  return  value  may  overflow  the  possible  range  of  type  clock _t.  If  the 

306  times ()  function  fails,  a  value  of  (( clock  Jt )  -1)  is  returned  and  errno  is  set  to  indi- 

307  cate  the  error. 

308  4.5.2.4  Errors 

309  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

310  to  be  detected  for  the  times( )  function.  Some  errors  may  be  detected  under  condi-  | 

311  tions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  | 

312  4.5.2.5  Cross-References 

313  exec,  3.1.2;  fork{ ),  3.1.1;  sysconfO,  4.8.1;  time{),  4.5.1;  wait(),  3.2.1.  | 

314  4.6  Environment  Variables 

315  4.6.1  Environment  Access 

316  Function:  getenvO 

317  4.6.1. 1  Synopsis 

318  #include  <stdlib.h> 

319  char  *getenv  (const  char  *name)  ; 

320  4.6.1.2  Description 

321  The  getenv{)  function  searches  the  environment  list  (see  2.6)  for  a  string  of  the 

322  form  name=value  and  returns  a  pointer  to  value  if  such  a  string  is  present.  If  the 

323  specified  name  cannot  be  found,  a  NULL  pointer  is  returned. 
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324  4'6.1.3  Returns 

325  Upon  successful  completion,  the  getenv  ()  function  returns  a  pointer  to  a  string 

326  containing  the  value  for  the  specified  name,  or  a  NULL  pointer  if  the  specified 

327  name  cannot  be  found.  The  return  value  from  getenv  ()  may  point  to  static  data 

328  and,  therefore,  may  be  overwritten  by  each  call.  Unsuccessful  completion  shall 

329  result  in  the  return  of  a  NULL  pointer. 

330  4.6.1.4  Errors 

331  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

332  to  be  detected  for  the  getenv  ()  function.  Some  errors  may  be  detected  under  condi-  | 

333  tions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  | 

334  4.6.1.5  Cross-References 

335  3.1.2;  2.6. 

336  4.7  Terminal  Identification 

337  4.7.1  Generate  Terminal  Pathname 

338  Function:  ctermidO 

339  4.7. 1.1  Synopsis 

340  #include  <stdio.h> 

341  char  *ctermid  (char  *s)  ; 

342  4.7.1.2  Description 

343  The  ctermidO  function  generates  a  string  that,  when  used  as  a  pathname,  refers 

344  to  the  current  controlling  terminal  for  the  current  process. 

345  If  the  ctermidO  function  returns  a  pathname,  access  to  the  file  is  not  guaranteed. 

346  4.7.1.3  Returns 

347  If  s  is  a  NULL  pointer,  the  string  is  generated  in  an  area  that  may  be  static  (and, 

348  therefore,  may  be  overwritten  by  each  call),  the  address  of  which  is  returned. 

349  Otherwise,  s  is  assumed  to  point  to  an  array  of  char  of  at  least  L_ctermid  bytes;  | 

350  the  string  is  placed  in  this  array  and  the  value  of  s  is  returned.  The  symbolic  con- 

351  stant  L_ctermid  is  defined  in  <stdio.h>  and  shall  have  a  value  greater  than 

352  zero. 

353  The  ctermidO  function  shall  return  an  empty  string  if  the  pathname  that  would 

354  refer  to  the  controlling  terminal  cannot  be  determined  or  if  the  function  is 

355  unsuccessful. 
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356  4. 7. 1.4  Errors 

357  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

358  to  be  detected  for  the  cterm id ()  function.  Some  errors  may  be  detected  under  con-  | 

359  ditions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  | 

360  4.7.1.5  Cross-References 

361  tty  name  (),  4.7.2. 

362  4.7.2  Determine  Terminal  Device  Name 

363  Functions:  tty  name  (),isatty() 

364  4.7.2. 1  Synopsis 

365  char  *ttyname(int  fildes)  ; 

366  int  isatty(int  fildes); 

367  4.7.2.2  Description 

368  The  ttyname  ()  function  returns  a  pointer  to  a  string  containing  a  null-terminated 

369  pathname  of  the  terminal  associated  with  file  descriptor  fildes . 

370  The  return  value  of  ttyname ()  may  point  to  static  data  that  is  overwritten  by  each 

371  call. 

372  The  isattyi)  function  returns  1  if  fildes  is  a  valid  file  descriptor  associated  with  a 

373  terminal,  zero  otherwise. 

374  4.7.2.S  Returns 

375  The  ttyname  ()  function  returns  a  NULL  pointer  if  fildes  is  not  a  valid  file  descrip- 

376  tor  associated  with  a  terminal  or  if  the  pathname  cannot  be  determined. 

377  4.7.2.4  Errors 

378  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

379  to  be  detected  for  the  ttyname ()  or  isattyi)  functions.  Some  errors  may  be  | 

380  detected  under  conditions  that  are  unspecified  by  this  part  of  ISO/IEC  9945. 
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381  4.8  Configurable  System  Variables 

382  4.8.1  Get  Configurable  System  Variables 

383  Function:  sysconfi) 

384  4.8.1. 1  Synopsis 

385  #include  <unistd.h> 

386  long  sysconf(int  name); 

387  4.8.1.2  Description 

388  The  sysconfi )  function  provides  a  method  for  the  application  to  determine  the 

389  current  value  of  a  configurable  system  limit  or  option  {variable). 

390  The  name  argument  represents  the  system  variable  to  be  queried.  The  implemen- 

391  tation  shall  support  all  of  the  variables  listed  in  Table  4-2  and  may  support  oth- 

392  ers.  The  variables  in  Table  4-2  come  from  <limits  .  h>  or  <unistd.h>  and  the  | 

393  symbolic  constants,  defined  in  <unistd.h>,  that  are  the  corresponding  values  | 

394  used  for  name . 


395  Table  4-2  -  Configurable  System  Variables 

396  _ 


397 

Variable 

name  Value 

398 

(ARG_MAX) 

LSC_ARG_MAX) 

399 

{CHILD_MAX} 

LSC_CHILD_MAX} 

400 

clock  ticks/second 

LSC_CLK_TCK) 

401 

{N  GROUPS_MAX) 

LSC_NGROUPS_MAX) 

402 

(OPEN.MAX) 

(_SC_OPEN_MAX} 

403 

{STREAM_MAX} 

{_SC_STREAM_MAX} 

404 

{TZNAME_MAX} 

LSC_TZNAME_MAX) 

405 

{_POSIX_J  OB_CONTROL) 

{_SC_J  OB_CONTRO  L} 

406 

LPOSIX_SAVED_IDS) 

(_SC_SAVED_IDS} 

407 

LPOSIXVERSION} 

{_SC_VERSION} 

408 

409  4.8.1.3  Returns 

410  If  name  is  an  invalid  value,  sysconfi)  shall  return  -1.  If  the  variable  correspond-  | 

411  ing  to  name  is  associated  with  functionality  that  is  not  supported  by  the  system,  | 

412  sysconfi)  shall  return  -1  without  changing  the  value  of  errno.  \ 

413  Otherwise,  the  sysconfi)  function  returns  the  current  variable  value  on  the  sys- 

414  tern.  The  value  returned  shall  not  be  more  restrictive  than  the  corresponding 

415  value  described  to  the  application  when  it  was  compiled  with  the 

416  implementation’s  <limits  .h>  or  <unistd.h>.  The  value  shall  not  change  dur- 

417  ing  the  lifetime  of  the  calling  process. 
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418  4.8. 1.4  Errors 

419  If  any  of  the  following  conditions  occur,  the  sysconfi)  function  shall  return  -1  and 

420  set  errno  to  the  corresponding  value: 

421  [EINVAL]  The  value  of  the  name  argument  is  invalid. 

422  4.8.1.5  Special  Symbol  {CLK_TCK}  | 

423  The  special  symbol  {CLK_TCK}  shall  yield  the  same  result  as  | 

424  sysconf  (_sc_clk_tck)  .  It  shall  be  defined  in  <time.h>.  The  symbol  | 

425  {CLK_TCK}  may  be  evaluated  by  the  implementation  at  run  time  or  may  be  a  con-  | 

426  stant.  This  special  symbol  is  obsolescent. 
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Section  5:  Files  and  Directories 


1  The  functions  in  this  section  perform  the  operating  system  services  dealing  with 

2  the  creation  and  removal  of  files  and  directories  and  the  detection  and 

3  modification  of  their  characteristics.  They  also  provide  the  primary  methods  a 

4  process  will  use  to  gain  access  to  files  and  directories  for  subsequent  I/O  opera- 

5  tions  (see  Section  6). 


6  5.1  Directories 


7  5.1.1  Format  of  Directory  Entries 


8  The  header  <dirent .  h>  defines  a  structure  and  a  defined  type  used  by  the  direc- 

9  tory  routines. 


10 

n 

12 

13 

14 

15 


The  internal  format  of  directories  is  unspecified. 


The  readdir ()  function  returns  a  pointer  to  an  object  of  type  struct  dirent  that 
includes  the  member: 


Member  Member 
Type  Name 

char  [  ]  djname 


Description 

Null-terminated  filename 


16  The  array  of  char  djiame  is  of  unspecified  size,  but  the  number  of  bytes  preceding  | 

17  the  terminating  null  character  shall  not  exceed  {NAME_MAX}. 


is  5.1.2  Directory  Operations 

19  Functions:  opendir(),  readdiri),  rewinddir(),  closedir() 

20  5. 1.2.1  Synopsis 

21  #include  <sys/types . h> 

22  #include  <dirent.h> 

23  dir  *opendir  (const  char  *dirname) ; 

24  struct  dirent  *readdir(DIR  *dirp)  ; 

25  void  rewinddir  (DIR  *dirp)  ; 

26  int  closedir(DIR  *dirp)  ; 
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5. 1.2.2  Description 

The  type  DIR ,  which  is  defined  in  the  header  <dirent.h>,  represents  a  directory 
stream,  which  is  an  ordered  sequence  of  all  the  directory  entries  in  a  particular 
directory.  Directory  entries  represent  files;  files  may  be  removed  from  a  directory 
or  added  to  a  directory  asynchronously  to  the  operations  described  in  this  sub-  | 
clause  (5.1.2).  The  type  DIR  may  be  implemented  using  a  file  descriptor.  In  that 
case,  applications  will  only  be  able  to  open  up  to  a  total  of  {OPEN_MAX}  files  and 
directories;  see  5.3.1.  A  successful  call  to  any  of  the  exec  functions  shall  close  any  | 
directory  streams  that  are  open  in  the  calling  process. 

The  opendir()  function  opens  a  directory  stream  corresponding  to  the  directory 
named  by  the  dirname  argument.  The  directory  stream  is  positioned  at  the  first 
entry. 

The  readdir ()  function  returns  a  pointer  to  a  structure  representing  the  directory 
entry  at  the  current  position  in  the  directory  stream  to  which  dirp  refers,  and 
positions  the  directory  stream  at  the  next  entry.  It  returns  a  NULL  pointer  upon 
reaching  the  end  of  the  directory  stream. 

The  readdir ( )  function  shall  not  return  directory  entries  containing  empty  names. 

It  is  unspecified  whether  entries  are  returned  for  dot  or  dot-dot.  | 

The  pointer  returned  by  readdir ()  points  to  data  that  may  be  overwritten  by 
another  call  to  readdir ()  on  the  same  directory  stream.  This  data  shall  not  be 
overwritten  by  another  call  to  readdir ()  on  a  different  directory  stream. 

The  readdirO  function  may  buffer  several  directory  entries  per  actual  read  opera¬ 
tion;  the  readdir( )  function  shall  mark  for  update  the  st_atime  field  of  the  direc¬ 
tory  each  time  the  directory  is  actually  read. 

The  rewinddir( )  function  resets  the  position  of  the  directory  stream  to  which  dirp 
refers  to  the  beginning  of  the  directory.  It  also  causes  the  directory  stream  to 
refer  to  the  current  state  of  the  corresponding  directory,  as  a  call  to  opendir{ ) 
would  have  done.  It  does  not  return  a  value. 

If  a  file  is  removed  from  or  added  to  the  directory  after  the  most  recent  call  to 
opendir()  or  rewinddir(),  whether  a  subsequent  call  to  readdirO  returns  an  entry 
for  that  file  is  unspecified. 

The  closedir( )  function  closes  the  directory  stream  referred  to  by  dirp  and  returns 
a  value  of  zero  if  successful.  Otherwise,  it  returns  -1  indicating  an  error.  Upon 
return,  the  value  of  dirp  may  no  longer  point  to  an  accessible  object  of  type  DIR. 

If  a  file  descriptor  is  used  to  implement  type  DIR,  that  file  descriptor  shall  be 
closed. 

If  the  dirp  argument  passed  to  any  of  these  functions  does  not  refer  to  a  currently 
open  directory  stream,  the  effect  is  undefined. 

The  result  of  using  a  directory  stream  after  one  of  the  exec  family  of  functions  is 
undefined.  After  a  call  to  the  fork()  function,  either  the  parent  or  the  child  (but 
not  both)  may  continue  processing  the  directory  stream  using  readdir( )  or  rewind- 
dir()  or  both.  If  both  the  parent  and  child  processes  use  these  functions,  the 
result  is  undefined.  Either  or  both  processes  may  use  closedir( ). 
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70  5. 1.2.3  Returns 

71  Upon  successful  completion,  opendir ()  returns  a  pointer  to  an  object  of  type  DIR. 

72  Otherwise,  a  value  of  NULL  is  returned  and  errno  is  set  to  indicate  the  error. 

73  Upon  successful  completion,  readdiri)  returns  a  pointer  to  an  object  of  type  struct 

74  dirent.  When  an  error  is  encountered,  a  value  of  NULL  is  returned  and  errno  is 

75  set  to  indicate  the  error.  When  the  end  of  the  directory  is  encountered,  a  value  of 

76  NULL  is  returned  and  errno  is  unchanged  by  this  function  call. 

77  Upon  successful  completion,  closedir( )  returns  a  value  of  zero.  Otherwise,  a  value 

78  of  -1  is  returned  and  errno  is  set  to  indicate  the  error. 


79  5.1.2.4  Errors 


so  If  any  of  the  following  conditions  occur,  the  opendir  ()  function  shall  return  a  value 

81  of  NULL  and  set  errno  to  the  corresponding  value: 

82  [EACCES]  Search  permission  is  denied  for  a  component  of  the  path  prefix  | 

83  of  dirname ,  or  read  permission  is  denied  for  the  directory  itself.  | 


84 

85 

86 
87 


[ENAMETOOLONG] 

The  length  of  the  dirname  argument  exceeds  {PATH_MAX},  or  a 
pathname  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_N 0_TRUN C }  is  in  effect. 


88  [ENOENT]  The  named  directory  does  not  exist,  or  dirname  points  to  an  | 

89  empty  string. 


90  [ENOTDIR]  A  component  of  dirname  is  not  a  directory. 


91  For  each  of  the  following  conditions,  when  the  condition  is  detected,  the  opendir{ ) 

92  function  shall  return  a  value  of  NULL  and  set  errno  to  the  corresponding  value: 


93  [EMFILE]  Too  many  file  descriptors  are  currently  open  for  the  process. 

94  [ENFILE]  Too  many  file  descriptors  are  currently  open  in  the  system. 


95  For  each  of  the  following  conditions,  when  the  condition  is  detected,  the  readdir{ ) 

96  function  shall  return  a  value  of  NULL  and  set  errno  to  the  corresponding  value: 


97  [EBADF]  The  dirp  argument  does  not  refer  to  an  open  directory  stream. 


98  For  each  of  the  following  conditions,  when  the  condition  is  detected,  the  closedir{ ) 

99  function  shall  return  -1  and  set  errno  to  the  corresponding  value: 


100  [EBADF]  The  dirp  argument  does  not  refer  to  an  open  directory  stream. 


101  5. 1.2.5  Cross-References 

102  <dirent  .h>,  5.1.1. 
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103  5.2  Working  Directory 


104  5.2.1  Change  Current  Working  Directory 

105  Function:  chdir{) 

106  5.2. 1.1  Synopsis 

107  int  chdir  (const  char  *path)  ; 

108  5.2.1.2  Description 

109  The  path  argument  points  to  the  pathname  of  a  directory.  The  chdir ()  function 
no  causes  the  named  directory  to  become  the  current  working  directory,  that  is,  the 

111  starting  point  for  path  searches  of  pathnames  not  beginning  with  slash. 

112  If  the  chdiri)  function  fails,  the  current  working  directory  shall  remain 

113  unchanged  by  this  function  call. 

114  5.2.1.3  Returns 

115  Upon  successful  completion,  a  value  of  zero  is  returned.  Otherwise,  a  value  of  -1 

116  is  returned  and  errno  is  set  to  indicate  the  error. 


U7  5.2.1.4  Errors 


us  If  any  of  the  following  conditions  occur,  the  chdir()  function  shall  return  -1  and 

119  set  errno  to  the  corresponding  value: 

120  [EACCES1  Search  permission  is  denied  for  any  component  of  the  path- 

121  name. 


122 

123 

124 

125 


[ENAMETOOLONG] 

The  path  argument  exceeds  {PATH_MAX}  in  length,  or  a  path¬ 
name  component  is  longer  than  {NAME_MAX}  while 
LPOSIX_NO_TRUNC}  is  in  effect. 


126  [ENOTDIR]  A  component  of  the  pathname  is  not  a  directory. 

127  [ENOENT]  The  named  directory  does  not  exist  or  path  is  an  empty  string. 


128  5.2.1.5  Cross-References 

129  getcwdi),  5.2.2. 
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130  5.2.2  Get  Working  Directory  Pathname  | 

131  Function:  getcwdO 

132  5.2.2.1  Synopsis 

133  char  *getcwd(char  *buf,  size_t  size); 

134  5.2.2.2  Description 

135  The  getcwdO  function  copies  an  absolute  pathname  of  the  current  working  direc- 

136  tory  to  the  array  of  char  pointed  to  by  the  argument  buf  and  returns  a  pointer  to  | 

137  the  result.  The  size  argument  is  the  size  in  bytes  of  the  array  of  char  pointed  to  | 

138  by  the  buf  argument.  If  buf  is  a  NULL  pointer,  the  behavior  of  getcwdO  is 

139  undefined. 

140  5.2.2.3  Returns 

141  If  successful,  the  buf  argument  is  returned.  A  NULL  pointer  is  returned  if  an 

142  error  occurs  and  the  variable  errno  is  set  to  indicate  the  error.  The  contents  of  buf 

143  after  an  error  are  undefined. 

144  5.2.2.4  Errors 

145  If  any  of  the  following  conditions  occur,  the  getcwdO  function  shall  return  a  value 

146  of  NULL  and  set  errno  to  the  corresponding  value: 

147  [EINVAL]  The  size  argument  is  zero. 

148  [ERANGE]  The  size  argument  is  greater  than  zero  but  smaller  than  the 

149  length  of  the  pathname  plus  1. 

150  For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  getcwdO  func- 

151  tion  shall  return  a  value  of  NULL  and  set  errno  to  the  corresponding  value: 

152  [EACCES]  Read  or  search  permission  was  denied  for  a  component  of  the 

153  pathname. 

154  5.2.2.5  Cross-References 

155  chdirO,  5.2.1. 


5.2  Working  Directory 


87 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


INFORMATION  TECHNOLOGY— POSIX 


156  5.3  General  File  Creation 


157  5.3.1  Open  a  File 

158  Function:  open  () 

159  5.3. 1.1  Synopsis 

160  #include  <sys/types  .  h> 

161  #include  <sys/stat.h> 

162  #include  <fcntl.h> 

163  int  open  (const  char  *path,  int  oflag,  .  .  .  ); 


164  5.3. 1.2  Description 


165  The  open  ()  function  establishes  the  connection  between  a  file  and  a  file  descriptor. 

166  It  creates  an  open  file  description  that  refers  to  a  file  and  a  file  descriptor  that 

167  refers  to  that  open  file  description.  The  file  descriptor  is  used  by  other  I/O  func- 

168  tions  to  refer  to  that  file.  The  path  argument  points  to  a  pathname  naming  a  file. 

169  The  open  ()  function  shall  return  a  file  descriptor  for  the  named  file  that  is  the 

170  lowest  file  descriptor  not  currently  open  for  that  process.  The  open  file  description 

171  is  new,  and  therefore  the  file  descriptor  does  not  share  it  with  any  other  process 

172  in  the  system.  The  file  offset  shall  be  set  to  the  beginning  of  the  file.  The  | 

173  FD_CLOEXEC  file  descriptor  flag  associated  with  the  new  file  descriptor  shall  be  | 

174  cleared.  The  file  status  flags  and  file  access  modes  of  the  open  file  description 

175  shall  be  set  according  to  the  value  of  oflag.  The  value  of  oflag  is  the  bitwise 

176  inclusive  OR  of  values  from  the  following  list.  See  6.5.1  for  the  definitions  of  the 

177  symbolic  constants.  Applications  shall  specify  exactly  one  of  the  first  three  values 

178  (file  access  modes)  below  in  the  value  of  oflag : 


179 

180 

181 

182 

183 


0_RDONLY  Open  for  reading  only. 

0_WRONLY  Open  for  writing  only. 

0_RDWR  Open  for  reading  and  writing.  The  result  is  undefined  if  this 
flag  is  applied  to  a  FIFO. 

Any  combination  of  the  remaining  flags  may  be  specified  in  the  value  of  oflag : 


184 

185 


0_APPEND  If  set,  the  file  offset  shall  be  set  to  the  end  of  the  file  prior  to 
each  write. 


186 

187 

188 

189 

190 

191 

192 

193 

194 

195 


0_CREAT  This  option  requires  a  third  argument,  mode,  which  is  of  type 
modej.  If  the  file  exists,  this  flag  has  no  effect,  except  as  noted 
under  0_EXCL,  below.  Otherwise,  the  file  is  created;  the  file’s 
user  ID  shall  be  set  to  the  effective  user  ID  of  the  process;  the 
file’s  group  ID  shall  be  set  to  the  group  ID  of  the  directory  in 
which  the  file  is  being  created  or  to  the  effective  group  ID  of  the 
process.  The  file  permission  bits  (see  5.6.1)  shall  be  set  to  the 
value  of  mode  except  those  set  in  the  file  mode  creation  mask  of 
the  process  (see  5.3.3).  When  bits  in  mode  other  than  the  file 
permission  bits  are  set,  the  effect  is  unspecified.  The  mode 
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argument  does  not  affect  whether  the  file  is  opened  for  reading,  | 
for  writing,  or  for  both. 

0_EXCL  If  0_EXCL  and  0_CREAT  are  set,  open()  shall  fail  if  the  file 
exists.  The  check  for  the  existence  of  the  file  and  the  creation  of 
the  file  if  it  does  not  exist  shall  be  atomic  with  respect  to  other 
processes  executing  open{)  naming  the  same  filename  in  the 
same  directory  with  0_EXCL  and  0_CREAT  set.  If  0_EXCL  is 
set  and  0_CREAT  is  not  set,  the  result  is  undefined. 

0_NOCTTY  If  set,  and  path  identifies  a  terminal  device,  the  open{)  function 
shall  not  cause  the  terminal  device  to  become  the  controlling 
terminal  for  the  process  (see  7.1. 1.3). 

CLNONBLOCK 

(1)  When  opening  a  FIFO  with  0_RDONLY  or  0_WRONLY  set: 

(a)  If  CLNONBLOCK  is  set: 

An  open  ()  for  reading-only  shall  return  without 
delay.  An  open  ()  for  writing-only  shall  return  an 
error  if  no  process  currently  has  the  file  open  for 
reading. 

(b)  If  CLNONBLOCK  is  clear: 

An  open()  for  reading-only  shall  block  until  a  process 
opens  the  file  for  writing.  An  open  ()  for  writing-only 
shall  block  until  a  process  opens  the  file  for  reading. 

(2)  When  opening  a  block  special  or  character  special  file  that 
supports  nonblocking  opens: 

(a)  If  CLNONBLOCK  is  set: 

The  open  ()  shall  return  without  waiting  for  the  dev¬ 
ice  to  be  ready  or  available.  Subsequent  behavior  of 
the  device  is  device-specific. 

(b)  If  CLNONBLOCK  is  clear: 

The  open  ()  shall  wait  until  the  device  is  ready  or 
available  before  returning. 

(3)  Otherwise,  the  behavior  of  0_NONBLOCK  is  unspecified. 

0_TRUNC  If  the  file  exists  and  is  a  regular  file,  and  the  file  is  successfully 
opened  0_RDWR  or  0_WRONLY,  it  shall  be  truncated  to  zero 
length  and  the  mode  and  owner  shall  be  unchanged  by  this 
function  call.  0_TRUNC  shall  have  no  effect  on  FIFO  special 
files  or  terminal  device  files.  Its  effect  on  other  file  types  is  | 
implementation  defined.  The  result  of  using  0_TRUNC  with 
0_RDONLY  is  undefined. 

If  0_CREAT  is  set  and  the  file  did  not  previously  exist,  upon  successful  completion 
the  open()  function  shall  mark  for  update  the  st_atime ,  stjctime,  and  stjntime 
fields  of  the  file  and  the  stjctime  and  stjntime  fields  of  the  parent  directory. 
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238  If  0_TRUNC  is  set  and  the  file  did  previously  exist,  upon  successful  completion 

239  the  open()  function  shall  mark  for  update  the  st_ctime  and  stjntime  fields  of  the 

240  file. 

241  5.3.1.3  Returns 

242  Upon  successful  completion,  the  function  shall  open  the  file  and  return  a  nonne- 

243  gative  integer  representing  the  lowest  numbered  unused  file  descriptor.  Other- 

244  wise,  it  shall  return  -1  and  shall  set  errno  to  indicate  the  error.  No  files  shall  be 

245  created  or  modified  if  the  function  returns  -1. 


246  5.3. 1.4  Errors 


247  If  any  of  the  following  conditions  occur,  the  open()  function  shall  return  -1  and  set 

248  errno  to  the  corresponding  value: 


249 

250 

251 

252 

253 


[EACCES]  Search  permission  is  denied  on  a  component  of  the  path  prefix, 
or  the  file  exists  and  the  permissions  specified  by  oflag  are 
denied,  or  the  file  does  not  exist  and  write  permission  is  denied 
for  the  parent  directory  of  the  file  to  be  created,  or  0_TRUNC  is 
specified  and  write  permission  is  denied. 


254 


[EEXIST]  0_CREAT  and  0_EXCL  are  set  and  the  named  file  exists. 


255 

256 

257 


[EINTR]  The  open{)  operation  was  interrupted  by  a  signal. 

[EISDIR]  The  named  file  is  a  directory,  and  the  oflag  argument  specifies 
write  or  read/write  access. 


258  [EMFILE]  Too  many  file  descriptors  are  currently  in  use  by  this  process. 


259 

260 
261 
262 


[ENAMETOOLONG] 

The  length  of  the  path  string  exceeds  {PATH_MAX},  or  a  path¬ 
name  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_NO_TRUNC}  is  in  effect. 


263  [ENFILE]  Too  many  files  are  currently  open  in  the  system. 


264 

265 

266 


[ENOENT]  0_CREAT  is  not  set  and  the  named  file  does  not  exist,  or 
0_CREAT  is  set  and  either  the  path  prefix  does  not  exist  or  the 
path  argument  points  to  an  empty  string. 


267  [ENOSPC]  The  directory  or  file  system  that  would  contain  the  new  file  can- 

268  not  be  extended. 


269  [ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 

270  [ENXIO]  CLNONBLOCK  is  set,  the  named  file  is  a  FIFO,  0_WR0NLY  is 

271  set,  and  no  process  has  the  file  open  for  reading. 


272 

273 

274 


[EROFS]  The  named  file  resides  on  a  read-only  file  system  and  either 

CLWRONLY,  0_RDWR,  0_CREAT  (if  the  file  does  not  exist),  or 
0_TRUNC  is  set  in  the  oflag  argument. 
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275  5.3.1.5  Cross-References 

276  close (),  6.3.1;  creat(),  5.3.2; dup{),  6.2.1;  exec,  3.1.2;  fcntl(),  6.5.2;  <fcntl.h>, 

277  6.5.1;  Iseek (),  6.5.3;  read(),  6.4.1;  <signal  .h>,  3.3.1;  stat(),  5.6.2; 

278  <sys/stat  .h>,  5.6.1;  write{),  6.4.2;  umask (),  5.3.3;  3.3. 1.4. 

279  5.3.2  Create  a  New  File  or  Rewrite  an  Existing  One 

280  Function:  creat () 

281  5.3.2.1  Synopsis 

282  #include  <sys/types  .  h> 

283  #include  <sys/stat.h> 

284  #include  <fcntl.h> 

285  int  creat  (const  char  *path,  mode_t  mode)  ; 

286  5.3.2.2  Description 

287  The  function  call: 

288  creat  (path,  mode)  ; 

289  is  equivalent  to: 

290  open  (path,  0_wronly  |  0_creat  I  O _ trunc  ,  mode); 

291  5.3.2.3  Cross-References 

292  open(),  5.3.1;  <sys/stat  .h>,  5.6.1. 

293  5.3.3  Set  File  Creation  Mask 

294  Function:  umask  () 

295  5.3.3.1  Synopsis 

296  #include  <sys/types  .  h> 

297  #include  <sys/stat.h> 

298  mode_t  umask  (mode_t  cmask)  ; 

299  5.3.3.2  Description 

300  The  umask  ()  routine  sets  the  file  mode  creation  mask  of  the  process  to  cmask  and 

301  returns  the  previous  value  of  the  mask.  Only  the  file  permission  bits  (see  5.6.1)  of 

302  cmask  are  used;  the  meaning  of  the  other  bits  is  implementation  defined. 

303  The  file  mode  creation  mask  of  the  process  is  used  during  open(),  creat ( ),  mkdir( ), 

304  and  mkfifoO  calls  to  turn  off  permission  bits  in  the  mode  argument  supplied.  Bit 

305  positions  that  are  set  in  cmask  are  cleared  in  the  mode  of  the  created  file. 
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306  5.3.3.3  Returns 

307  The  file  permission  bits  in  the  value  returned  by  umask  ()  shall  be  the  previous  | 

308  value  of  the  file  mode  creation  mask.  The  state  of  any  other  bits  in  that  value  is  | 

309  unspecified,  except  that  a  subsequent  call  to  umask  ()  with  that  returned  value  as  | 

310  cmask  shall  leave  the  state  of  the  mask  the  same  as  its  state  before  the  first  call,  | 

311  including  any  unspecified  (by  this  part  of  ISO/IEC  9945)  use  of  those  bits. 

312  5.S.3.4  Errors 

313  The  umask ()  function  is  always  successful,  and  no  return  value  is  reserved  to 

314  indicate  an  error. 

315  5.3.3.5  Cross-References 

316  chmodO,  5.6.4;  creatO,  5.3.2;  mkdir(),  5.4.1;  mkfifoO,  5.4.2;  open (),  5.3.1; 

317  <sys/stat . h>,  5.6.1. 

318  5.3.4  Link  to  a  File 

319  Function:  link () 

320  5.3.4.1  Synopsis 

321  int  link  (const  char  *existing,  const  char  *new)  ; 

322  5.3.4.2  Description 

323  The  argument  existing  points  to  a  pathname  naming  an  existing  file.  The  argu-  | 

324  ment  new  points  to  a  pathname  naming  the  new  directory  entry  to  be  created.  | 

325  Implementations  may  support  linking  of  files  across  file  systems.  The  link  ()  func- 

326  tion  shall  atomically  create  a  new  link  for  the  existing  file  and  increment  the  link 

327  count  of  the  file  by  one. 

328  If  the  link  ()  function  fails,  no  link  shall  be  created,  and  the  link  count  of  the  file 

329  shall  remain  unchanged  by  this  function  call. 

330  The  existing  argument  shall  not  name  a  directory  unless  the  user  has  appropriate  | 

331  privileges  and  the  implementation  supports  using  link{ )  on  directories. 

332  The  implementation  may  require  that  the  calling  process  has  permission  to  access 

333  the  existing  file. 

334  Upon  successful  completion,  the  link  ()  function  shall  mark  for  update  the  stjctime 

335  field  of  the  file.  Also,  the  stjctime  and  stjntime  fields  of  the  directory  that  con- 

336  tains  the  new  entry  are  marked  for  update. 
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337  5.3.4.3  Returns 

338  Upon  successful  completion,  link()  shall  return  a  value  of  zero.  Otherwise,  a 

339  value  of  — 1  is  returned  and  errno  is  set  to  indicate  the  error. 


340  5.3.4.4  Errors 


341  If  any  of  the  following  conditions  occur,  the  link  ()  function  shall  return  -1  and  set 

342  errno  to  the  corresponding  value: 


343 

344 

345 

346 

347 


[EACCES]  A  component  of  either  path  prefix  denies  search  permission;  or 
the  requested  link  requires  writing  in  a  directory  with  a  mode 
that  denies  write  permission;  or  the  calling  process  does  not 
have  permission  to  access  the  existing  file,  and  this  is  required 
by  the  implementation. 


348 

349 

350 


[EEXIST]  The  link  named  by  new  exists. 

[EMLINK]  The  number  of  links  to  the  file  named  by  existing  would  exceed 
{LINK_MAX}. 


351 

352 

353 

354 


[ENAMETOOLONG] 

The  length  of  the  existing  or  new  string  exceeds  {PATH_MAX},  | 
or  a  pathname  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_NO_TRUNC}  is  in  effect. 


355 

356 

357 


[ENOENT]  A  component  of  either  path  prefix  does  not  exist,  the  file  named 

by  existing  does  not  exist,  or  either  existing  or  new  points  to  an  | 
empty  string. 


358  [ENOSPC1  The  directory  that  would  contain  the  link  cannot  be  extended. 

359  [ENOTDIR]  A  component  of  either  path  prefix  is  not  a  directory. 


360 

361 

362 


[EPERM]  The  file  named  by  existing  is  a  directory,  and  either  the  calling  | 
process  does  not  have  appropriate  privileges  or  the  implemen¬ 
tation  prohibits  using  link{)  on  directories. 


363  [EROFS]  The  requested  link  requires  writing  in  a  directory  on  a  read- 

364  only  file  system. 


365 

366 

367 


[EXDEV]  The  link  named  by  new  and  the  file  named  by  existing  are  on  | 
different  file  systems,  and  the  implementation  does  not  support 
links  between  file  systems. 


368  5.3.4.5  Cross-References 

369  rename (),  5.5.3;  unlink (),  5.5.1. 
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370  5.4  Special  File  Creation 


371  5.4.1  Make  a  Directory 

372  Function:  mkdir( ) 

373  5.4.1. 1  Synopsis 

374  #include  <sys/types  . h> 

375  #include  <sys/stat.h> 

376  int  mkdir  (const  char  *path,  mode_t  mode); 

377  5.4.1.2  Description 

378  The  mkdir( )  routine  creates  a  new  directory  with  name  path .  The  file  permission 

379  bits  of  the  new  directory  are  initialized  from  mode.  The  file  permission  bits  of  the 

380  mode  argument  are  modified  by  the  file  creation  mask  of  the  process  (see  5.3.3). 

381  When  bits  in  mode  other  than  the  file  permission  bits  are  set,  the  meaning  of 

382  these  additional  bits  is  implementation  defined. 

383  The  owner  ID  of  the  directory  is  set  to  the  effective  user  ID  of  the  process.  The 

384  directory’s  group  ID  shall  be  set  to  the  group  ID  of  the  directory  in  which  the  direc- 

385  tory  is  being  created  or  to  the  effective  group  ID  of  the  process. 

386  The  newly  created  directory  shall  be  an  empty  directory. 

387  Upon  successful  completion,  the  mkdir( )  function  shall  mark  for  update  the 

388  st_atime,  stjctime,  and  stjntime  fields  of  the  directory.  Also,  the  stjctime  and 

389  stjntime  fields  of  the  directory  that  contains  the  new  entry  are  marked  for 

390  update. 

391  5.4.1.3  Returns 

392  A  return  value  of  zero  indicates  success.  A  return  value  of  -1  indicates  that  an 

393  error  has  occurred,  and  an  error  code  is  stored  in  errno.  No  directory  shall  be 

394  created  if  the  return  value  is  -1. 


395  5.4.1.4  Errors 


396  If  any  of  the  following  conditions  occur,  the  mkdir( )  function  shall  return  -1  and 

397  set  errno  to  the  corresponding  value: 


398 

399 

400 


[EACCES]  Search  permission  is  denied  on  a  component  of  the  path  prefix, 
or  write  permission  is  denied  on  the  parent  directory  of  the 
directory  to  be  created. 


401  [EEXIST]  The  named  file  exists. 


402  [EMLINK]  The  link  count  of  the  parent  directory  would  exceed 

403  {LINK_MAX}. 
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404  [ENAMETOOLONG] 


405 

406 

407 

The  length  of  the  path  argument  exceeds  {PATH_MAX},  or  a 
pathname  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_NO_TRUNC}  is  in  effect. 

408 

409 

[ENOENT] 

A  component  of  the  path  prefix  does  not  exist,  or  the  path  argu¬ 
ment  points  to  an  empty  string. 

410 

411 

412 

[ENOSPC] 

The  file  system  does  not  contain  enough  space  to  hold  the  con¬ 
tents  of  the  new  directory  or  to  extend  the  parent  directory  of 
the  new  directory. 

413 

[ENOTDIR1 

A  component  of  the  path  prefix  is  not  a  directory. 

414 

415 

[EROFS1 

The  parent  directory  of  the  directory  being  created  resides  on  a 
read-only  file  system. 

416  5.4.1.5  Cross-References 

417  chmod(),  5.6.4;  stat (),  5.6.2;  <sys/stat .  h>,  5.6.1;  umask(),  5.3.3. 

418  5.4.2  Make  a  FIFO  Special  File 

419  Function:  mkfifo () 

420  5.4.2. 1  Synopsis 

421  #include  <sys/types  . h> 

422  #include  <sys/stat.h> 

423  int  mkfifo  (const  char  *path,  mode_t  mode); 

424  5.4.2.2  Description 

425  The  mkfifoO  routine  creates  a  new  FIFO  special  file  named  by  the  pathname 

426  pointed  to  by  path .  The  file  permission  bits  of  the  new  FIFO  are  initialized  from 

427  mode .  The  file  permission  bits  of  the  mode  argument  are  modified  by  the  file  crea- 

428  tion  mask  of  the  process  (see  5.3.3).  When  bits  in  mode  other  than  the  file  permis- 

429  sion  bits  are  set,  the  effect  is  implementation  defined. 

430  The  owner  ID  of  the  FIFO  shall  be  set  to  the  effective  user  ID  of  the  process.  The 

431  group  ID  of  the  FIFO  shall  be  set  to  the  group  ID  of  the  directory  in  which  the  FIFO 

432  is  being  created  or  to  the  effective  group  ID  of  the  process. 

433  Upon  successful  completion,  the  mkfifoO  function  shall  mark  for  update  the 

434  stjatime,  stjctime,  and  stjntime  fields  of  the  file.  Also,  the  stjctime  and  stjntime 

435  fields  of  the  directory  that  contains  the  new  entry  are  marked  for  update. 

436  5.4.2.3  Returns 

437  Upon  successful  completion,  a  value  of  zero  is  returned.  Otherwise,  a  value  of-1 

438  is  returned,  no  FIFO  is  created,  and  errno  is  set  to  indicate  the  error. 
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439  5.4.2.4  Errors 


440  If  any  of  the  following  conditions  occur,  the  mkfifoO  function  shall  return  -1  and 

441  set  errno  to  the  corresponding  value: 


442 

443 

444 


[EACCES]  Search  permission  is  denied  on  a  component  of  the  path  prefix,  | 
or  write  permission  is  denied  on  the  parent  directory  of  the  file  | 
to  be  created. 


445  [EEXIST]  The  named  file  already  exists. 


446 

447 

448 

449 


[ENAMETOOLONG] 

The  length  of  the  path  string  exceeds  {PATH_MAX},  or  a  path¬ 
name  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_NO_TRUNC}  is  in  effect. 


450  [ENOENT]  A  component  of  the  path  prefix  does  not  exist,  or  the  path  argu- 

451  ment  points  to  an  empty  string. 


452  [ENOSPC]  The  directory  that  would  contain  the  new  file  cannot  be 

453  extended,  or  the  file  system  is  out  of  file  allocation  resources. 


454  [ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 


455 


[EROFS]  The  named  file  resides  on  a  read-only  file  system. 


456  5.4.2.5  Cross-References 

457  chmod (),  5.6.4;  exec ,  3.1.2; pipe (),  6.1.1;  stat (),  5.6.2;  <sys/stat  ,h>,  5.6.1; 

458  umaskO,  5.3.3. 


459  5.5  File  Removal 

460  5.5.1  Remove  Directory  Entries 

461  Function:  unlinkO 

462  5.5.1. 1  Synopsis 

463  int  unlink  (const  char  *path)  ; 

464  5.5.1.2  Description 

465  The  unlinkO  function  shall  remove  the  link  named  by  the  pathname  pointed  to  by 

466  path  and  decrement  the  link  count  of  the  file  referenced  by  the  link. 

467  When  the  link  count  of  the  file  becomes  zero  and  no  process  has  the  file  open,  the 

468  space  occupied  by  the  file  shall  be  freed  and  the  file  shall  no  longer  be  accessible. 

469  If  one  or  more  processes  have  the  file  open  when  the  last  link  is  removed,  the  link 

470  shall  be  removed  before  unlinkO  returns,  but  the  removal  of  the  file  contents  shall 

471  be  postponed  until  all  references  to  the  file  have  been  closed. 
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The  path  argument  shall  not  name  a  directory  unless  the  process  has  appropriate 
privileges  and  the  implementation  supports  using  unlink ()  on  directories.  Appli¬ 
cations  should  use  rmdir( )  to  remove  a  directory. 

Upon  successful  completion,  the  unlink  ()  function  shall  mark  for  update  the 
stjctime  and  st_mtime  fields  of  the  parent  directory.  Also,  if  the  link  count  of  the 
file  is  not  zero,  the  stjctime  field  of  the  file  shall  be  marked  for  update. 

5.5.1.3  Returns 

Upon  successful  completion,  a  value  of  zero  shall  be  returned.  Otherwise,  a  value 
of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error.  If  -1  is 
returned,  the  named  file  shall  not  be  changed  by  this  function  call. 

5.5. 1.4  Errors 

If  any  of  the  following  conditions  occur,  the  unlink  ()  function  shall  return  -1  and 
set  errno  to  the  corresponding  value: 

[EACCES1  Search  permission  is  denied  for  a  component  of  the  path  prefix, 
or  write  permission  is  denied  on  the  directory  containing  the 
link  to  be  removed. 

[EBUSY]  The  directory  named  by  the  path  argument  cannot  be  unlinked 
because  it  is  being  used  by  the  system  or  another  process  and 
the  implementation  considers  this  to  be  an  error. 

[ENAMETOOLONG] 

The  length  of  the  path  argument  exceeds  {PATH_MAX},  or  a 
pathname  component  is  longer  than  {NAME_MAX}  while 
{_PO S IX_N 0_TRUN C }  is  in  effect. 

The  named  file  does  not  exist,  or  the  path  argument  points  to 
an  empty  string. 

A  component  of  the  path  prefix  is  not  a  directory. 

The  file  named  by  path  is  a  directory,  and  either  the  calling 
process  does  not  have  appropriate  privileges  or  the  implemen¬ 
tation  prohibits  using  unlinki.)  on  directories. 

The  directory  entry  to  be  unlinked  resides  on  a  read-only  file 
system. 

5.5.1.5  Cross-References 

close (),  6.3.1;  link (),  5.3.4;  open(),  5.3.1;  renamed),  5.5.3;  rmdir(),  5.5.2. 


[ENOENT] 

[ENOTDIR] 

[EPERM] 

[EROFS1 
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5.5.2  Remove  a  Directory 

Function:  rmdir() 

5.5.2. 1  Synopsis 

int  rmdir  (const  char  *path)  ; 

5.5.2.2  Description 

The  rmdir()  function  removes  a  directory  whose  name  is  given  by  path.  The 
directory  shall  be  removed  only  if  it  is  an  empty  directory. 

If  the  named  directory  is  the  root  directory  or  the  current  working  directory  of  any  | 
process,  it  is  unspecified  whether  the  function  succeeds  or  whether  it  fails  and  | 
sets  errno  to  [EBUSY]. 

If  the  link  count  of  the  directory  becomes  zero  and  no  process  has  the  directory 
open,  the  space  occupied  by  the  directory  shall  be  freed  and  the  directory  shall  no 
longer  be  accessible.  If  one  or  more  processes  have  the  directory  open  when  the 
last  link  is  removed,  the  dot  and  dot-dot  entries,  if  present,  are  removed  before 
rmdir( )  returns  and  no  new  entries  may  be  created  in  the  directory,  but  the  direc¬ 
tory  is  not  removed  until  all  references  to  the  directory  have  been  closed. 

Upon  successful  completion,  the  rmdir{)  function  shall  mark  for  update  the 
stjctime  and  stjntime  fields  of  the  parent  directory. 

5.5.2.3  Returns 

Upon  successful  completion,  a  value  of  zero  shall  be  returned.  Otherwise,  a  value  | 
of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error.  If  -1  is  | 
returned,  the  named  directory  shall  not  be  changed  by  this  function  call.  | 

5.5.2.4  Errors 

If  any  of  the  following  conditions  occur,  the  rmdir( )  function  shall  return  -1  and 
set  errno  to  the  corresponding  value: 

[EACCES]  Search  permission  is  denied  on  a  component  of  the  path  prefix,  | 
or  write  permission  is  denied  on  the  parent  directory  of  the  | 
directory  to  be  removed.  | 

[EBUSY]  The  directory  named  by  the  path  argument  cannot  be  removed 
because  it  is  being  used  by  another  process  and  the  implemen¬ 
tation  considers  this  to  be  an  error. 

[EEXIST]  or  [ENOTEMPTY] 

The  path  argument  names  a  directory  that  is  not  an  empty 
directory. 

[ENAMETOOLONG] 

The  length  of  the  path  argument  exceeds  {PATH_MAX},  or  a 
pathname  component  is  longer  than  {NAME_MAX}  while 
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542 


{_POS IX_N 0_TRUN C }  is  in  effect. 


543  [ENOENT]  The  path  argument  names  a  nonexistent  directory  or  points  to 

544  an  empty  string. 

545  [ENOTDIR]  A  component  of  the  path  is  not  a  directory. 

546  [EROFS]  The  directory  entry  to  be  removed  resides  on  a  read-only  file 

547  system. 


548  5.5.2.5  Cross-References 

549  mkdir(),  5.4.1;  unlink (),  5.5.1. 


550  5.5.3  Rename  a  File 

551  Function:  rename () 

552  5.5.3.1  Synopsis 

553  int  rename  (const  char  *old,  const  char  *new)  ; 

554  5.5.3.2  Description 

555  The  rename  ()  function  changes  the  name  of  a  file.  The  old  argument  points  to  the 

556  pathname  of  the  file  to  be  renamed.  The  new  argument  points  to  the  new  path- 

557  name  of  the  file. 

558  If  the  old  argument  and  the  new  argument  both  refer  to  links  to  the  same  existing 

559  file,  the  rename ()  function  shall  return  successfully  and  perform  no  other  action. 

560  If  the  old  argument  points  to  the  pathname  of  a  file  that  is  not  a  directory,  the 

561  new  argument  shall  not  point  to  the  pathname  of  a  directory.  If  the  link  named 

562  by  the  new  argument  exists,  it  shall  be  removed  and  old  renamed  to  new .  In  this 

563  case,  a  link  named  new  shall  exist  throughout  the  renaming  operation  and  shall 

564  refer  either  to  the  file  referred  to  by  new  or  old  before  the  operation  began.  Write 

565  access  permission  is  required  for  both  the  directory  containing  old  and  the  direc- 

566  tory  containing  new . 

567  If  the  old  argument  points  to  the  pathname  of  a  directory,  the  new  argument  shall 

568  not  point  to  the  pathname  of  a  file  that  is  not  a  directory.  If  the  directory  named 

569  by  the  new  argument  exists,  it  shall  be  removed  and  old  renamed  to  new.  In  this 

570  case,  a  link  named  new  shall  exist  throughout  the  renaming  operation  and  shall 

571  refer  either  to  the  file  referred  to  by  new  or  old  before  the  operation  began.  Thus, 

572  if  new  names  an  existing  directory,  it  shall  be  required  to  be  an  empty  directory. 

573  The  new  pathname  shall  not  contain  a  path  prefix  that  names  old.  Write  access 

574  permission  is  required  for  the  directory  containing  old  and  the  directory  contain- 

575  ing  new.  If  the  old  argument  points  to  the  pathname  of  a  directory,  write  access 

576  permission  may  be  required  for  the  directory  named  by  old ,  and,  if  it  exists,  the 

577  directory  named  by  new. 
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578  If  the  link  named  by  the  new  argument  exists  and  the  link  count  of  the  file 

579  becomes  zero  when  it  is  removed  and  no  process  has  the  file  open,  the  space  occu- 

580  pied  by  the  file  shall  be  freed  and  the  file  shall  no  longer  be  accessible.  If  one  or 

581  more  processes  have  the  file  open  when  the  last  link  is  removed,  the  link  shall  be 

582  removed  before  renamed)  returns,  but  the  removal  of  the  file  contents  shall  be 

583  postponed  until  all  references  to  the  file  have  been  closed. 

584  Upon  successful  completion,  the  rename ()  function  shall  mark  for  update  the 

585  stjctime  and  stjntime  fields  of  the  parent  directory  of  each  file. 

586  5.5.3.3  Returns 

587  Upon  successful  completion,  a  value  of  zero  shall  be  returned.  Otherwise,  a  value  | 

588  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error.  If  -1  is  | 

589  returned,  neither  the  file  named  by  old  nor  the  file  named  by  new ,  if  either  exists,  | 

590  shall  be  changed  by  this  function  call. 


591  5.5.3.4  Errors 


592  If  any  of  the  following  conditions  occur,  the  rename  ()  function  shall  return  -1  and 

593  set  errno  to  the  corresponding  value: 

594  [EACCES]  A  component  of  either  path  prefix  denies  search  permission,  or 

595  one  of  the  directories  containing  old  or  new  denies  write  per- 

596  missions,  or  write  permission  is  required  and  is  denied  for  a 

597  directory  pointed  to  by  the  old  or  new  arguments. 

598  [EBUSYl  The  directory  named  by  old  or  new  cannot  be  renamed  because 

599  it  is  being  used  by  the  system  or  another  process  and  the  imple- 

600  mentation  considers  this  to  be  an  error. 

601  [E EXIST]  or  [ENOTEMPTY] 

602  The  link  named  by  new  is  a  directory  containing  entries  other 

603  than  dot  and  dot-dot. 


604  [EINVAL]  The  new  directory  pathname  contains  a  path  prefix  that  names 

605  the  old  directory. 


606  [EISDIR]  The  new  argument  points  to  a  directory,  and  the  old  argument 

607  points  to  a  file  that  is  not  a  directory. 


608 

609 

610 
611 


[ENAMETOOLONG] 

The  length  of  the  old  or  new  argument  exceeds  {PATH_MAX},  or 
a  pathname  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_NO_TRUNC}  is  in  effect. 


612 

613 

614 

615 


[EMLINK]  The  file  named  by  old  is  a  directory,  and  the  link  count  of  the  | 
parent  directory  of  new  would  exceed  {LINK_MAX}. 

[ENOENT]  The  link  named  by  the  old  argument  does  not  exist,  or  either 
old  or  new  points  to  an  empty  string. 


616  [ENOSPC]  The  directory  that  would  contain  new  cannot  be  extended. 
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617 

618 
619 


[ENOTDIR]  A  component  of  either  path  prefix  is  not  a  directory,  or  the  old 
argument  names  a  directory  and  the  new  argument  names  a 
nondirectory  file. 


620  [EROFS]  The  requested  operation  requires  writing  in  a  directory  on  a 

621  read-only  file  system. 


622 

623 

624 


[EXDEV]  The  links  named  by  new  and  old  are  on  different  file  systems, 
and  the  implementation  does  not  support  links  between  file 
systems. 


625  5.5.3.5  Cross-References 

626  link(),  5.3.4;  rmdir(),  5.5.2;  unlinkO,  5.5.1. 


627  5.6  File  Characteristics 

628  5.6.1  File  Characteristics:  Header  and  Data  Structure 

629  The  header  <sys/stat.h>  defines  the  structure  stat,  which  includes  the 

630  members  shown  in  Table  5-1,  returned  by  the  functions  stat( )  and  fstat{ ). 


631 

632 

Table  5-1  -  stat  Structure 

633 

Member 

Member 

Description 

634 

Type 

Name 

635 

modejt 

stjnode 

File  mode  (see  5.6. 1.2). 

636 

inojt 

st_i.no 

File  serial  number. 

637 

deujt 

stjdev 

ID  of  device  containing  this  file. 

638 

nlinkjt 

stjilink 

Number  of  links. 

639 

uid_t 

stjuid 

User  ID  of  the  owner  of  the  file. 

640 

gidjt 

st_gid 

Group  ID  of  the  group  of  the  file. 

641 

642 

offj 

stjsize 

For  regular  files,  the  file  size  in  bytes.  For  other  file  types,  the  use  of 
this  field  is  unspecified. 

643 

timejt 

stjatime 

Time  of  last  access. 

644 

timejt 

stjntime 

Time  of  last  data  modification. 

645 

646 

timejt 

stjctime 

Time  of  last  file  status  change. 

647  NOTE:  File  serial  number  and  device  ID  taken  together  uniquely  identify  the  file  within  the  system. 


648  All  of  the  described  members  shall  appear  in  the  stat  structure.  The  structure 

649  members  stjnode ,  st_ino,  stjdev,  stjuid,  st_gid,  stjatime,  stjctime,  and  stjntime 

650  shall  have  meaningful  values  for  all  file  types  defined  in  this  part  of  ISO/IEC  9945. 

651  The  value  of  the  member  stjilink  shall  be  set  to  the  number  of  links  to  the  file. 
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658 

659 

660 

661 

662 

663 

664 

665 

666 

667 

668 

669 

670 

671 
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673 

674 

675 

676 

677 

678 
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683 
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5.6.1.1  <sys/stat .  h>  File  Types 


The  following  macros  shall  test  whether  a  file  is  of  the  specified  type. 
m  supplied  to  the  macros  is  the  value  of  stjnode  from  a  stat  structure, 
evaluates  to  a  nonzero  value  if  the  test  is  true,  zero  if  the  test  is  false. 

S_ISDIR(m)  Test  macro  for  a  directory  file. 

S_ISCHR(ra)  Test  macro  for  a  character  special  file. 

S_ISBLK(m)  Test  macro  for  a  block  special  file. 

S_ISREG(m)  Test  macro  for  a  regular  file. 

S_ISFIFO(m)  Test  macro  for  a  pipe  or  a  FIFO  special  file. 


The  value 
The  macro 


5.6.1.2  <sys/stat ,h>  File  Modes 


The  file  modes  portion  of  values  of  type  modejt,  such  as  the  stjnode  value,  are 
bit-encoded  with  the  following  masks  and  bits: 

S_IRWXU  Read,  write,  search  (if  a  directory),  or  execute  (otherwise)  permis¬ 
sions  mask  for  the  file  owner  class. 

S_IRUSR  Read  permission  bit  for  the  file  owner  class. 

S_IWUSR  Write  permission  bit  for  the  file  owner  class. 

S_IXUSR  Search  (if  a  directory)  or  execute  (otherwise)  per¬ 
missions  bit  for  the  file  owner  class. 


S_IRWXG  Read,  write,  search  (if  a  directory),  or  execute  (otherwise)  permis¬ 
sions  mask  for  the  file  group  class. 

S_IRGRP  Read  permission  bit  for  the  file  group  class. 

SJTWGRP  Write  permission  bit  for  the  file  group  class. 

S_IXGRP  Search  (if  a  directory)  or  execute  (otherwise)  per¬ 
missions  bit  for  the  file  group  class. 

S_IRWXO  Read,  write,  search  (if  a  directory),  or  execute  (otherwise)  permis¬ 
sions  mask  for  the  file  other  class. 


S_IROTH  Read  permission  bit  for  the  file  other  class. 

S_IWOTH  Write  permission  bit  for  the  file  other  class. 

S_IXOTH  Search  (if  a  directory)  or  execute  (otherwise)  per¬ 
missions  bit  for  the  file  other  class. 

S_ISUID  Set  user  ID  on  execution.  The  effective  user  ID  of  the  process 
shall  be  set  to  that  of  the  owner  of  the  file  when  the  file  is  run  as 
a  program  (see  exec).  On  a  regular  file,  this  bit  should  be  cleared 
on  any  write. 

S_ISGID  Set  group  ID  on  execution.  Set  effective  group  ID  on  the  process  to 
the  group  of  the  file  when  the  file  is  run  as  a  program  (see  exec). 
On  a  regular  file,  this  bit  should  be  cleared  on  any  write. 
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689  The  bits  defined  by  SJRUSR,  S.IWUSR,  S_IXUSR,  S  JRGRP,  S_IWGRP,  SJXGRP, 

690  SJROTH,  SJWOTH,  S_IXOTH,  SJSUID,  and  SJSGID  shall  be  unique.  SJRWXU 

691  shall  be  the  bitwise  inclusive  OR  of  SJRUSR,  SJWUSR,  and  S_IXUSR.  SJRWXG 

692  shall  be  the  bitwise  inclusive  OR  of  S_IRGRP,  S_IWGRP,  and  SJXGRP.  S JRWXO 

693  shall  be  the  bitwise  inclusive  OR  of  SJROTH,  SJWOTH,  and  SJXOTH.  Imple- 

694  mentations  may  OR  other  implementation-defined  bits  into  SJRWXU,  SJRWXG, 

695  and  SJRWXO,  but  they  shall  not  overlap  any  of  the  other  bits  defined  in  this  part 

696  of  ISO/IEC  9945.  The  file  permission  bits  are  defined  to  be  those  corresponding  to 

697  the  bitwise  inclusive  OR  of  SJRWXU,  SJRWXG,  and  SJRWXO. 

698  5.6.1.3  <sys/stat.h>  Time  Entries 

699  The  time-related  fields  of  struct  stat  are  as  follows: 

700  st_atime  Accessed  file  data,  for  example,  readi). 

701  stjntime  Modified  file  data,  for  example,  writei). 

702  st_ctime  Changed  file  status,  for  example,  chmodi). 

703  These  times  are  updated  as  described  in  2.3.5. 

704 

705  Times  are  given  in  seconds  since  the  Epoch. 

706  5.6. 1.4  Cross-References 

707  chmod{ ),  5.6.4;  chowni),  5.6.5;  creati ),  5.3.2;  exec,  3.1.2;  linki),  5.3.4;  mkdiri), 

708  5.4.1;  mkfifoi),  5.4.2; pipe (),  6.1.1;  readi),  6.4.1;  unlinki),  5.5.1;  utimei),  5.6.6; 

709  writei),  6.4.2;  removei)  [C  Standard  {2}]. 

710  5.6.2  Get  File  Status 

711  Functions:  stat (),  f 'stat () 

712  5.6.2.1  Synopsis 

713  #include  <sys/types  .  h> 

714  #include  <sys/stat.h> 

715  int  stat  (const  char  *path,  struct  stat  *buf)  ; 

716  int  fstat(int  fildes,  struct  stat  *buf)  ; 

717  5.6.2.2  Description 

718  The  path  argument  points  to  a  pathname  naming  a  file.  Read,  write,  or  execute 

719  permission  for  the  named  file  is  not  required,  but  all  directories  listed  in  the  path- 

720  name  leading  to  the  file  must  be  searchable.  The  stati)  function  obtains  informa- 

721  tion  about  the  named  file  and  writes  it  to  the  area  pointed  to  by  the  buf  argument. 

722  Similarly,  the  f stati)  function  obtains  information  about  an  open  file  known  by  the 

723  file  descriptor  fildes . 
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724  An  implementation  that  provides  additional  or  alternate  file  access  control 

725  mechanisms  may,  under  implementation-defined  conditions,  cause  the  stat{)  and 

726  fstat ()  functions  to  fail.  In  particular,  the  system  may  deny  the  existence  of  the 

727  file  specified  by  path . 

728  Both  functions  update  any  time-related  fields,  as  described  in  2.3.5,  before  writing 

729  into  the  stat  structure. 

730  The  buf  is  taken  to  be  a  pointer  to  a  stat  structure,  as  defined  in  the  header 

731  <sys/stat .  h>,  into  which  information  is  placed  concerning  the  file. 

732  5.6.2.3  Returns 

733  Upon  successful  completion,  a  value  of  zero  shall  be  returned.  Otherwise,  a  value 

734  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error. 


735  5.6.2.4  Errors 


736  If  any  of  the  following  conditions  occur,  the  stat{)  function  shall  return  -1  and  set 

737  errno  to  the  corresponding  value: 

738  [EACCES]  Search  permission  is  denied  for  a  component  of  the  path  prefix. 

739  [ENAMETOOLONG] 

740  The  length  of  the  path  argument  exceeds  {PATH_MAX},  or  a 

741  pathname  component  is  longer  than  {NAME_MAX}  while 

742  {_POSIX_NO_TRUNC}  is  in  effect. 


743  [ENOENT]  The  named  file  does  not  exist,  or  the  path  argument  points  to 

744  an  empty  string. 


745  [ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 


746  If  any  of  the  following  conditions  occur,  the  fstat  ( )  function  shall  return  -1  and  set 

747  errno  to  the  corresponding  value: 


748  [EBADF]  The  fddes  argument  is  not  a  valid  file  descriptor. 


749  5.6.2.5  Cross-References 

750  creat{),  5.3.2;  dup{),  6.2.1;  fcntli),  6.5.2;  open(),  5.3.1; pipe (),  6.1.1; 

751  <sys/stat . h>,  5.6.1. 


752  5.6.3  Check  File  Accessibility 

753  Function:  access () 

754  5.6.3. 1  Synopsis 

755  #include  <unistd.h> 

756  int  access  (const  char  *path,  int  amode )  ; 
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757  5.6.3.2  Description 

758  The  accessO  function  checks  the  accessibility  of  the  file  named  by  the  pathname 

759  pointed  to  by  the  path  argument  for  the  file  access  permissions  indicated  by 

760  amode ,  using  the  real  user  ID  in  place  of  the  effective  user  ID  and  the  real  group 

761  ID  in  place  of  the  effective  group  ID. 

762  The  value  of  amode  is  either  the  bitwise  inclusive  OR  of  the  access  permissions  to 

763  be  checked  (R_OK,  W_OK,  and  X_OK)  or  the  existence  test  (F_OK).  See  2.9.1  for 

764  the  description  of  these  symbolic  constants. 

765  If  any  access  permission  is  to  be  checked,  each  shall  be  checked  individually,  as 

766  described  in  2.3.2.  If  the  process  has  appropriate  privileges,  an  implementation 

767  may  indicate  success  for  X_OK  even  if  none  of  the  execute  file  permission  bits  are 

768  set. 


769  5.6.3.3  Returns 

770  If  the  requested  access  is  permitted,  a  value  of  zero  shall  be  returned.  Otherwise, 

771  a  value  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error. 


772  5.6.3.4  Errors 


773  If  any  of  the  following  conditions  occur,  the  access ()  function  shall  return  -1  and 

774  set  errno  to  the  corresponding  value: 

775  [EACCES]  The  permissions  specified  by  amode  are  denied,  or  search  per- 

776  mission  is  denied  on  a  component  of  the  path  prefix. 


777 

778 

779 

780 


[ENAMETOOLONG] 

The  length  of  the  path  argument  exceeds  {PATH_MAX},  or  a 
pathname  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_NO_TRUNC}  is  in  effect. 


781  [ENOENT]  The  path  argument  points  to  an  empty  string  or  to  the  name  of 

782  a  file  that  does  not  exist. 


783  [ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 

784  [EROFS]  Write  access  was  requested  for  a  file  residing  on  a  read-only  file 

785  system. 

786  For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  access  ()  func- 

787  tion  shall  return  -1  and  set  errno  to  the  corresponding  value: 

788  [EINVAL]  An  invalid  value  was  specified  for  amode . 


789  5.6.3.5  Cross-References 

790  chmod(),  5.6.4;  stat(),  5.6.2;  <unistd.h>,  2.9. 
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791  5.6.4  Change  File  Modes 

792  Function:  chmodi) 

793  5.6.4. 1  Synopsis 

794  #include  <sys/types  . h> 

795  #include  <sys/stat.h> 

796  int  chmod  (const  char  *path,  mode_t  mode); 

797  5.6.4.2  Description 

798  The  path  argument  shall  point  to  a  pathname  naming  a  file.  If  the  effective  user 

799  ID  of  the  calling  process  matches  the  file  owner  or  the  calling  process  has 

800  appropriate  privileges,  the  chmodi)  function  shall  set  the  S_ISUID,  S_ISGID,  and 

801  the  file  permission  bits,  as  described  in  5.6.1,  of  the  named  file  from  the 

802  corresponding  bits  in  the  mode  argument.  These  bits  define  access  permissions 

803  for  the  user  associated  with  the  file,  the  group  associated  with  the  file,  and  all  oth- 

804  ers,  as  described  in  2.3.2.  Additional  implementation-defined  restrictions  may 

805  cause  the  S_ISUID  and  S_ISGID  bits  in  mode  to  be  ignored. 

806  If  the  calling  process  does  not  have  appropriate  privileges,  if  the  group  ID  of  the 

807  file  does  not  match  the  effective  group  ID  or  one  of  the  supplementary  group  IDs, 

808  and  if  the  file  is  a  regular  file,  bit  S_ISGID  (set  group  ID  on  execution)  in  the  mode 

809  of  the  file  shall  be  cleared  upon  successful  return  from  chmodi ). 

810  The  effect  on  file  descriptors  for  files  open  at  the  time  of  the  chmodi )  function  is 

811  implementation  defined. 

812  Upon  successful  completion,  the  chmodi)  function  shall  mark  for  update  the 

813  stjctime  field  of  the  file. 

814  5.6.4.3  Returns 

815  Upon  successful  completion,  the  function  shall  return  a  value  of  zero.  Otherwise, 

816  a  value  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error.  If  -1  is 

817  returned,  no  change  to  the  file  mode  shall  have  occurred. 

818  5.6.4.4  Errors 

819  If  any  of  the  following  conditions  occur,  the  chmodi)  function  shall  return  -1  and 

820  set  errno  to  the  corresponding  value: 

821  [EACCES]  Search  permission  is  denied  on  a  component  of  the  path  prefix. 

822  [ENAMETOOLONG] 

823  The  length  of  the  path  argument  exceeds  {PATH_MAX},  or  a 

824  pathname  component  is  longer  than  {NAME_MAX}  while 

825  {_POSIX_NO_TRUNC}  is  in  effect. 

826  [ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 
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[ENOENT]  The  named  file  does  not  exist  or  the  path  argument  points  to  an 
empty  string. 

[EPERM]  The  effective  user  ID  does  not  match  the  owner  of  the  file,  and 
the  calling  process  does  not  have  the  appropriate  privileges. 

[EROFS]  The  named  file  resides  on  a  read-only  file  system. 

5.6.4.5  Cross-References 

chown(),  5.6.5;  mkdir{),  5.4.1;  mkfifoi),  5.4.2;  stat{),  5.6.2;  <sys/stat .  h>,  5.6.1. 


5.6.5  Change  Owner  and  Group  of  a  File 

Function:  chown  () 

5.6.5. 1  Synopsis 

♦include  <sys/types . h> 

int  chown  (const  char  *path,  uid_t  owner,  gid_t  group); 

5.6.5.2  Description 

The  path  argument  points  to  a  pathname  naming  a  file.  The  user  ID  and  group  ID 
of  the  named  file  are  set  to  the  numeric  values  contained  in  owner  and  group 
respectively. 

Only  processes  with  an  effective  user  ID  equal  to  the  user  ID  of  the  file  or 
with  appropriate  privileges  may  change  the  ownership  of  a  file.  If 
{_POSIX_CHOWN_RESTRICTED}  is  in  effect  for  path: 

(1)  Changing  the  owner  is  restricted  to  processes  with  appropriate 
privileges. 

(2)  Changing  the  group  is  permitted  to  a  process  without  appropriate 
privileges,  but  with  an  effective  user  ID  equal  to  the  user  ID  of  the  file,  if 
and  only  if  owner  is  equal  to  the  user  ID  of  the  file  and  group  is  equal 
either  to  the  effective  group  ID  of  the  calling  process  or  to  one  of  its  sup¬ 
plementary  group  IDs. 

If  the  path  argument  refers  to  a  regular  file,  the  set-user-ID  (S_ISUID)  and  set- 
group-ID  (S_ISGID)  bits  of  the  file  mode  shall  be  cleared  upon  successful  return 
from  chown{),  unless  the  call  is  made  by  a  process  with  appropriate  privileges,  in 
which  case  it  is  implementation  defined  whether  those  bits  are  altered.  If  the 
chown  ( )  function  is  successfully  invoked  on  a  file  that  is  not  a  regular  file,  these 
bits  may  be  cleared.  These  bits  are  defined  in  5.6.1. 

Upon  successful  completion,  the  chown()  function  shall  mark  for  update  the 
stjctime  field  of  the  file. 


5.6  File  Characteristics 


107 


ISO/TEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


INFORMATION  TECHNOLOGY— POSIX 


861  5.6. 5.3  Returns 

862  Upon  successful  completion,  a  value  of  zero  shall  be  returned.  Otherwise,  a  value 

863  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error.  If  -1  is 

864  returned,  no  change  shall  be  made  in  the  owner  and  group  of  the  file. 


865  5.6.5.4  Errors 


866  If  any  of  the  following  conditions  occur,  the  chown{)  function  shall  return  -1  and 

867  set  errno  to  the  corresponding  value: 


868 

869 

870 

871 

872 


[EACCES]  Search  permission  is  denied  on  a  component  of  the  path  prefix. 
[ENAMETOOLONG] 

The  length  of  the  path  argument  exceeds  {PATH_MAX},  or  a 
pathname  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_NO_TRUNC}  is  in  effect. 


873  [ENOTDIRl  A  component  of  the  path  prefix  is  not  a  directory. 

874  [ENOENT]  The  named  file  does  not  exist,  or  the  path  argument  points  to 

875  an  empty  string. 


876 

877 

878 

879 


[EPERM]  The  effective  user  ID  does  not  match  the  owner  of  the  file,  or  the 
calling  process  does  not  have  appropriate  privileges  and 
{_POSIX_CHOWN_RESTRICTED}  indicates  that  such  privilege  is 
required. 


880  [EROFS]  The  named  file  resides  on  a  read-only  file  system. 


881  For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  chown()  func- 

882  tion  shall  return  -1  and  set  errno  to  the  corresponding  value: 

883  [EINVAL]  The  owner  or  group  ID  supplied  is  invalid  and  not  supported  by 

884  the  implementation. 


885  5.6.5.5  Cross-References 

886  chmodi),  5.6.4;  <sys/stat .  h>,  5.6.1. 


887  5.6.6  Set  File  Access  and  Modification  Times 

888  Function:  utime{ ) 

889  5.6.6.1  Synopsis 

890  #include  <sys/types  . h> 

891  #include  <utime.h> 

892  int  utime  (const  char  *path,  const  struct  utimbuf  Himes); 
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5.6.6.2  Description 

The  argument  path  points  to  a  pathname  naming  a  file.  The  utime ()  function  sets 
the  access  and  modification  times  of  the  named  file. 

If  the  times  argument  is  NULL,  the  access  and  modification  times  of  the  file  are 
set  to  the  current  time.  The  effective  user  ID  of  the  process  must  match  the  owner 
of  the  file,  or  the  process  must  have  write  permission  to  the  file  or  appropriate 
privileges,  to  use  the  utime ()  function  in  this  manner. 

If  the  times  argument  is  not  NULL,  it  is  interpreted  as  a  pointer  to  a  utimbuf 
structure,  and  the  access  and  modification  times  are  set  to  the  values  contained  in 
the  designated  structure.  Only  the  owner  of  the  file  and  processes  with  appropri¬ 
ate  privileges  shall  be  permitted  to  use  the  utimeO  function  in  this  way. 

The  utimbuf  structure  is  defined  by  the  header  <utime.h>  and  includes  the  fol¬ 
lowing  members: 


Member 

Type 

timejt 

time_t 


Member 

Name 

actime 

modtime 


Description 

Access  time 
Modification  time 


The  times  in  the  utimbuf  structure  are  measured  in  seconds  since  the  Epoch. 

Implementations  may  add  extensions  as  permitted  in  1.3. 1.1,  point  (2).  Adding  | 
extensions  to  this  structure,  which  might  change  the  behavior  of  the  application  | 
with  respect  to  this  standard  when  those  fields  in  the  structure  are  uninitialized,  | 
also  requires  that  the  extensions  be  enabled  as  required  by  1.3. 1.1.  | 

Upon  successful  completion,  the  utimeO  function  shall  mark  for  update  the 
stjctime  field  of  the  file. 

5.6.6.3  Returns 

Upon  successful  completion,  the  function  shall  return  a  value  of  zero.  Otherwise, 
a  value  of  -1  shall  be  returned,  errno  is  set  to  indicate  the  error,  and  the  file  times 
shall  not  be  affected. 


5.6.6.4  Errors 

If  any  of  the  following  conditions  occur,  the  utimeO  function  shall  return  -1  and 
set  errno  to  the  corresponding  value: 

[EACCES]  Search  permission  is  denied  by  a  component  of  the  path  prefix, 
or  the  times  argument  is  NULL  and  the  effective  user  ID  of  the 
process  does  not  match  the  owner  of  the  file  and  write  access  is 
denied. 

[ENAMETOOLONG] 

The  length  of  the  path  argument  exceeds  {PATH_MAX},  or  a 
pathname  component  is  longer  than  {NAME_MAX}  while 
{_POSIX_NO_TRUNC}  is  in  effect. 
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932  [ENOENT]  The  named  file  does  not  exist  or  the  path  argument  points  to  an 

933  empty  string. 


934  [ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 


935 

936 

937 

938 


[EPERM]  The  times  argument  is  not  NULL,  the  effective  user  ID  of  the 
calling  process  has  write  access  to  the  file,  but  does  not  match 
the  owner  of  the  file,  and  the  calling  process  does  not  have  the 
appropriate  privileges. 


939  [EROFS1  The  named  file  resides  on  a  read-only  file  system. 


940  5.6.6.5  Cross-References 

941  <sys/stat . h>,  5.6.1. 


942  5.7  Configurable  Pathname  Variables 

943  5.7.1  Get  Configurable  Pathname  Variables 

944  Functions:  pathconfO,  fpathconfO 

945  5.7.1. 1  Synopsis 

946  #include  <unistd.h> 

947  long  pathconf  (const  char  *path,  int  name)  ; 

948  long  f  pathconf  ( int  fildes ,  int  name); 

949  5.7.1.2  Description 

950  The  pathconf '( )  and  fpathconfi )  functions  provide  a  method  for  the  application  to 

951  determine  the  current  value  of  a  configurable  limit  or  option  ( variable )  that  is 

952  associated  with  a  file  or  directory. 

953  For  pathconfO,  the  path  argument  points  to  the  pathname  of  a  file  or  directory. 

954  For  fpathconfi ),  the  fildes  argument  is  an  open  file  descriptor. 

955  The  name  argument  represents  the  variable  to  be  queried  relative  to  that  file  or 

956  directory.  The  implementation  shall  support  all  of  the  variables  listed  in 

957  Table  5-2  and  may  support  others.  The  variables  in  Table  5-2  come  from 

958  <limits.h>  or  <unistd.h>  and  the  symbolic  constants,  defined  in 

959  <unistd . h>,  that  are  the  corresponding  values  used  for  name. 

960  5.7. 1.3  Returns 

961  If  name  is  an  invalid  value,  the  pathconfO  and  fpathconfO  functions  shall 

962  return  -1. 

963  If  the  variable  corresponding  to  name  has  no  limit  for  the  path  or  file  descriptor, 

964  the  pathconf i )  and  fpathconfi )  functions  shall  return  -1  without  changing  errno. 
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965  Table  5-2  -  Configurable  Pathname  Variables 

966  _ _ 


967 

Variable 

name  Value 

Notes 

968 

{LENK_MAX} 

{_PC_LINK_MAX} 

(1) 

969 

{MAX_CANON} 

(_PC_MAX_CANON) 

(2) 

970 

{MAXJNPUT} 

(_PC_MAX_INPUT) 

(2) 

971 

{NAME_MAX} 

(_PC_NAME_MAX| 

(3),  (4) 

972 

{PATH_MAX} 

{_PC_PATH_MAX} 

(4),  (5) 

973 

{PIPE_BUF} 

{_PC_PIPE_BUF} 

(6) 

974 

{_POSIX_CHOWN_RESTRICTED} 

{_PC_CH  O  WN_RE  STRICTED] 

(7) 

975 

(_POSDC_NO_TRUNC] 

LPC_NO_TRUNC] 

(3,  4) 

976 

977 

{_POSIX_VDISABLE} 

l_PC_VDISABLE} 

(2) 

978  NOTES: 


979 

980 

981 


(1)  If  path  or  fildes  refers  to  a  directory,  the  value  returned  applies  to  the  directory  itself. 

(2)  If  path  or  fildes  does  not  refer  to  a  terminal  file,  it  is  unspecified  whether  an  implementation 
supports  an  association  of  the  variable  name  with  the  specified  file. 


982  (3)  If  path  or  fildes  refers  to  a  directory,  the  value  returned  applies  to  the  filenames  within  the 

983  directory. 


984  (4)  If  path  or  fildes  does  not  refer  to  a  directory,  it  is  unspecified  whether  an  implementation 

985  supports  an  association  of  the  variable  name  with  the  specified  file. 


986  (5)  If  path  or  fildes  refers  to  a  directory,  the  value  returned  is  the  maximum  length  of  a  relative 

987  pathname  when  the  specified  directory  is  the  working  directory. 


988 

989 

990 

991 

992 


(6)  If  path  refers  to  a  FIFO,  or  fildes  refers  to  a  pipe  or  a  FIFO,  the  value  returned  applies  to  the 
referenced  object  itself.  If  path  or  fildes  refers  to  a  directory,  the  value  returned  applies  to 
any  FIFOs  that  exist  or  can  be  created  within  the  directory.  If  path  or  fildes  refers  to  any 
other  type  of  file,  it  is  unspecified  whether  an  implementation  supports  an  association  of  the 
variable  name  with  the  specified  file. 


993 

994 

995 


(7)  If  path  or  fildes  refers  to  a  directory,  the  value  returned  applies  to  any  files  defined  in  this 
part  of  ISO/IEC  9945,  other  than  directories,  that  exist  or  can  be  created  within  the 
directory. 


996  If  the  implementation  needs  to  use  path  to  determine  the  value  of  name  and  the 

997  implementation  does  not  support  the  association  of  name  with  the  file  specified  by 

998  path,  or  if  the  process  did  not  have  the  appropriate  privileges  to  query  the  file 

999  specified  by  path ,  or  path  does  not  exist,  the  pathconfi )  function  shall  return  -1. 

1000  If  the  implementation  needs  to  use  fildes  to  determine  the  value  of  name  and  the 

1001  implementation  does  not  support  the  association  of  name  with  the  file  specified  by 

1002  fildes,  or  if  fildes  is  an  invalid  file  descriptor,  the  fpathconfi)  function  shall 

1003  return  -1. 

1004  Otherwise,  the  pathconfO  and  fpathconfO  functions  return  the  current  variable 

1005  value  for  the  file  or  directory  without  changing  errno.  The  value  returned  shall 

1006  not  be  more  restrictive  than  the  corresponding  value  described  to  the  application 

1007  when  it  was  compiled  with  the  implementation’s  climits  .h>  or  <unistd.h>. 
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1008 

1009 

1010 

1011 

1012 

1013 

1014 

1015 

1016 

1017 

1018 

1019 

1020 

1021 

1022 

1023 

1024 

1025 

1026 

1027 
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5.7.1.4  Errors 

If  any  of  the  following  conditions  occur,  the  pathconfi )  and  fpathconfi )  functions 
shall  return  -1  and  set  errno  to  the  corresponding  value: 

[EINVAL]  The  value  of  name  is  invalid. 

For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  pathconfi ) 
function  shall  return  -1  and  set  errno  to  the  corresponding  value: 

[EACCES]  Search  permission  is  denied  for  a  component  of  the  path  prefix. 

[EINVAL]  The  implementation  does  not  support  an  association  of  the  vari¬ 
able  name  with  the  specified  file. 

[ENAMETOOLONG] 

The  length  of  the  path  argument  exceeds  [PATH_MAX],  or  a 
pathname  component  is  longer  than  [NAME_MAX]  while 
{_POSIX_NO_TRUNC}  is  in  effect. 

[ENOENT]  The  named  file  does  not  exist,  or  the  path  argument  points  to 
an  empty  string. 

[ENOTDIR]  A  component  of  the  path  prefix  is  not  a  directory. 

For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  fpathconfi ) 
function  shall  return  -1  and  set  errno  to  the  corresponding  value: 

[EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

[EINVAL]  The  implementation  does  not  support  an  association  of  the  vari¬ 

able  name  with  the  specified  file. 
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Section  6:  Input  and  Output  Primitives 


1  The  functions  in  this  section  deal  with  input  and  output  from  files  and  pipes.  | 

2  Functions  are  also  specified  that  deal  with  the  coordination  and  management  of 

3  file  descriptors  and  I/O  activity. 


4  6.1  Pipes 

5  6.1.1  Create  an  Inter-Process  Channel 

6  Function:  pipe () 

7  6.1.1. 1  Synopsis 

8  int  pipe(int  fildes  [ 2]); 

9  6.1. 1.2  Description 

10  The  pipe ()  function  shall  create  a  pipe  and  place  two  file  descriptors,  one  each  into 

n  the  arguments  fildes[ 0]  and  fildesi  1],  that  refer  to  the  open  file  descriptions  for 

12  the  read  and  write  ends  of  the  pipe.  Their  integer  values  shall  be  the  two  lowest 

13  available  at  the  time  of  the  pipe ()  function  call.  The  0_NONBLOCK  and  | 

14  FD_CLOEXEC  flags  shall  be  clear  on  both  file  descriptors.  [The  fcntl ()  function  | 

15  can  be  used  to  set  these  flags.]  | 

16  Data  can  be  written  to  file  descriptor  fildes[  1]  and  read  from  file  descriptor 

17  fildes[ 0].  A  read  on  file  descriptor  fildes[ 0]  shall  access  the  data  written  to  file 

is  descriptor  fildes [  1]  on  a  first-in-first-out  basis. 

19  A  process  has  the  pipe  open  for  reading  if  it  has  a  file  descriptor  open  that  refers 

20  to  the  read  end,  fildes[0].  A  process  has  the  pipe  open  for  writing  if  it  has  a  file 

21  descriptor  open  that  refers  to  the  write  end,  fildesi  1]. 

22  Upon  successful  completion,  the  pipe  ()  function  shall  mark  for  update  the 

23  st_atime ,  stjctime ,  and  stjntime  fields  of  the  pipe. 

24  6.1. 1.3  Returns 

25  Upon  successful  completion,  the  function  shall  return  a  value  of  zero.  Otherwise, 

26  a  value  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error. 
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27  6.1. 1.4  Errors 


28  If  any  of  the  following  conditions  occur,  the  pipe( )  function  shall  return  -1  and  set 

29  errno  to  the  corresponding  value: 


30  [EMFILE]  More  than  {OPEN_MAX}-2  file  descriptors  are  already  in  use  by 

31  this  process. 


32 

33 


[ENFILE] 


The  number  of  simultaneously  open  files  in  the  system  would 
exceed  a  system-imposed  limit. 


34  6.1. 1.5  Cross-References 

35  fcntl(),  6.5.2;  open(),  5.3.1;  read{),  6.4.1;  write (),  6.4.2. 


36  6.2  File  Descriptor  Manipulation 


37  6.2.1  Duplicate  an  Open  File  Descriptor 

38  Functions:  dup(),  dup2() 

39  6.2. 1.1  Synopsis 

40  int  dup(int  fildes)  ; 

41  int  dup2  (int  fildes,  int  fildes2)  ; 


42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 


6.2. 1.2  Description 

The  dup  ()  and  dup2{ )  functions  provide  an  alternate  interface  to  the  service  pro¬ 
vided  by  the  fcntl()  function  using  the  F_DUPFD  command.  The  call: 

fid  =  dup  (fildes) ; 

shall  be  equivalent  to: 

fid  =  fcntl  (fildes,  F_DUPFD,  0); 

The  call: 

fid  =  dup2  (fildes,  fildes2) ; 
shall  be  equivalent  to: 

close  (fildes2) ; 

fid  =  fcntl  (fildes,  F_DUPFD,  fildes2) ; 
except  for  the  following: 

(1)  If  fildes2  is  negative  or  greater  than  or  equal  to  {OPEN_MAX},  the  dup2( )  | 

function  shall  return  -1  and  errno  shall  be  set  to  [EBADF]. 

(2)  If  fildes  is  a  valid  file  descriptor  and  is  equal  to  fildes2,  the  dup2{)  func¬ 
tion  shall  return  fildes2  without  closing  it. 
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58  (3)  If  fildes  is  not  a  valid  file  descriptor,  dup2{ )  shall  fail  and  not  close 

59  fildes2 . 


60  (4)  The  value  returned  shall  be  equal  to  the  value  of  fldes2  upon  successful  | 

61  completion  or  shall  be  -1  upon  failure.  | 


62  6.2. 1.3  Returns 

63  Upon  successful  completion,  the  function  shall  return  a  file  descriptor.  Other- 

64  wise,  a  value  of-1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error. 


65  6.2. 1.4  Errors 


66  If  any  of  the  following  conditions  occur,  the  dup  ()  function  shall  return  -1  and  set 

67  errno  to  the  corresponding  value: 

68  [EBADFl  The  argument  fildes  is  not  a  valid  open  file  descriptor. 

69  [EMFILE]  The  number  of  file  descriptors  would  exceed  {OPEN_MAX}. 

70  If  any  of  the  following  conditions  occur,  the  dup2()  function  shall  return  -1  and 

71  set  errno  to  the  corresponding  value: 

72  [EBADFl  The  argument  fildes  is  not  a  valid  open  file  descriptor,  or  the 

73  argument  fildes2  is  negative  or  greater  than  or  equal  to 

74  {OPEN_MAX}. 


75  [EINTR]  The  dup2()  function  was  interrupted  by  a  signal. 


76  6.2. 1.5  Cross-References 

77  close (),  6.3.1;  creatO,  5.3.2;  exec,  3.1.2;  fcntlO,  6.5.2;  open{),  5.3.1; pipei),  6.1.1. 


78  6.3  File  Descriptor  Deassignment 

79  6.3.1  Close  a  File 

so  Function:  close () 

81  6.3. 1.1  Synopsis 

82  int  close  (int  fildes); 

83  6.3. 1.2  Description 

84  The  close ()  function  shall  deallocate  (i.e.,  make  available  for  return  by  subsequent 

85  open() s,  etc.,  executed  by  the  process)  the  file  descriptor  indicated  by  fildes.  All 

86  outstanding  record  locks  owned  by  the  process  on  the  file  associated  with  the  file 

87  descriptor  shall  be  removed  (that  is,  unlocked). 
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88  If  the  close ()  function  is  interrupted  by  a  signal  that  is  to  be  caught,  it  shall 

89  return  -1  with  errno  set  to  [EINTR],  and  the  state  of  fildes  is  unspecified. 

90  When  all  file  descriptors  associated  with  a  pipe  or  FIFO  special  file  have  been 

91  closed,  any  data  remaining  in  the  pipe  or  FIFO  shall  be  discarded. 

92  When  all  file  descriptors  associated  with  an  open  file  description  have  been  closed, 

93  the  open  file  description  shall  be  freed. 

94  If  the  link  count  of  the  file  is  zero,  when  all  file  descriptors  associated  with  the  file 

95  have  been  closed,  the  space  occupied  by  the  file  shall  be  freed  and  the  file  shall  no 

96  longer  be  accessible. 

97  6.3. 1.3  Returns 

98  Upon  successful  completion,  a  value  of  zero  shall  be  returned.  Otherwise,  a  value 

99  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the  error. 

100  6.3. 1.4  Errors 

101  If  any  of  the  following  conditions  occur,  the  close{)  function  shall  return  -1  and 

102  set  errno  to  the  corresponding  value: 

103  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

104  [EINTR]  The  close  function  was  interrupted  by  a  signal. 

105  6.3.1.5  Cross-References 

106  creatO ,  5.3.2;  dup{),  6.2.1  ;exec,  3.1.2 ;fcntl(),  6.5.2 \fork{),  3.1.1;  open (),  5.3.1; 

107  pipe (),  6.1.1;  unlink (),  5.5.1;  3. 3.1.4. 

108  6.4  Input  and  Output 

109  6.4.1  Read  from  a  File 

no  Function:  read() 

in  6.4.1. 1  Synopsis 

112  ssize_t  read(int  fildes,  void  *buf,  size  t  nbyte)  ; 

113  6.4.1.2  Description 

114  The  read()  function  shall  attempt  to  read  nbyte  bytes  from  the  file  associated  with 

115  the  open  file  descriptor,  fildes ,  into  the  buffer  pointed  to  by  buf. 

116  If  nbyte  is  zero,  the  read()  function  shall  return  zero  and  have  no  other  results. 

117  On  a  regular  file  or  other  file  capable  of  seeking,  read{)  shall  start  at  a  position  in 
ns  the  file  given  by  the  file  offset  associated  with  fildes.  Before  successful  return 
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from  readi),  the  file  offset  shall  be  incremented  by  the  number  of  bytes  actually 
read. 

On  a  file  not  capable  of  seeking,  the  read ()  shall  start  from  the  current  position. 
The  value  of  a  file  offset  associated  with  such  a  file  is  undefined. 

Upon  successful  completion,  the  readi )  function  shall  return  the  number  of  bytes 
actually  read  and  placed  in  the  buffer.  This  number  shall  never  be  greater  than 
nbyte.  The  value  returned  may  be  less  than  nbyte  if  the  number  of  bytes  left  in 
the  file  is  less  than  nbyte,  if  the  readi )  request  was  interrupted  by  a  signal,  or  if 
the  file  is  a  pipe  (or  FIFO)  or  special  file  and  has  fewer  than  nbyte  bytes  immedi¬ 
ately  available  for  reading.  For  example,  a  read ()  from  a  file  associated  with  a 
terminal  may  return  one  typed  line  of  data. 

If  a  readi)  is  interrupted  by  a  signal  before  it  reads  any  data,  it  shall  return  -1 
with  errno  set  to  [EINTR]. 

If  a  readi)  is  interrupted  by  a  signal  after  it  has  successfully  read  some  data, 
either  it  shall  return  -1  with  errno  set  to  [EINTR],  or  it  shall  return  the  number  of 
bytes  read.  A  read ()  from  a  pipe  or  FIFO  shall  never  return  with  errno  set  to 
[EINTR]  if  it  has  transferred  any  data. 

No  data  transfer  shall  occur  past  the  current  end-of-file.  If  the  starting  position  is 
at  or  after  the  end-of-file,  zero  shall  be  returned.  If  the  file  refers  to  a  device  spe¬ 
cial  file,  the  result  of  subsequent  readi)  requests  is  implementation  defined. 

If  the  value  of  nbyte  is  greater  than  [SSIZE_MAX],  the  result  is  implementation  | 
defined.  | 

When  attempting  to  read  from  an  empty  pipe  (or  FIFO): 

(1)  If  no  process  has  the  pipe  open  for  writing,  read ()  shall  return  zero  to 
indicate  end-of-file. 

(2)  If  some  process  has  the  pipe  open  for  writing  and  0_NONBLOCK  is  set, 
readi)  shall  return  -1  and  set  errno  to  [EAGAIN]. 

(3)  If  some  process  has  the  pipe  open  for  writing  and  0_NONBLOCK  is  clear,  | 

readi)  shall  block  until  some  data  is  written  or  the  pipe  is  closed  by  all  | 
processes  that  had  the  pipe  open  for  writing.  | 

When  attempting  to  read  a  file  (other  than  a  pipe  or  FIFO)  that  supports  non- 
blocking  reads  and  has  no  data  currently  available: 

(1)  If  0_NONBLOCK  is  set,  readi)  shall  return  -1  and  set  errno  to  [EAGAIN]. 

(2)  If  0_NONBLOCK  is  clear,  readi)  shall  block  until  some  data  becomes 
available. 

The  use  of  the  0_NONBLOCK  flag  has  no  effect  if  there  is  some  data  available. 

For  any  portion  of  a  regular  file,  prior  to  the  end-of-file,  that  has  not  been  written, 
readi)  shall  return  bytes  with  value  zero. 

Upon  successful  completion  where  nbyte  is  greater  than  zero,  the  readi)  function  | 
shall  mark  for  update  the  st_atime  field  of  the  file. 
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159  6.4. 1.3  Returns 

160  Upon  successful  completion,  read ()  shall  return  an  integer  indicating  the  number 

161  of  bytes  actually  read.  Otherwise,  read()  shall  return  a  value  of-1  and  set  errno 

162  to  indicate  the  error,  and  the  content  of  the  buffer  pointed  to  by  buf  is 

163  indeterminate. 


164  6.4.1.4  Errors 


165  If  any  of  the  following  conditions  occur,  the  read{)  function  shall  return  -1  and  set 

166  errno  to  the  corresponding  value: 


167  [EAGAIN]  The  0_NONBLOCK  flag  is  set  for  the  file  descriptor  and  the  pro- 

168  cess  would  be  delayed  in  the  read  operation. 


169  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor  open  for 

170  reading. 


171 

172 

173 


[EINTR]  The  read  operation  was  interrupted  by  a  signal,  and  either  no 

data  was  transferred  or  the  implementation  does  not  report 
partial  transfer  for  this  file. 


174  [EIO] 

175 

176 

177 

178 

179 


The  implementation  supports  job  control,  the  process  is  in  a 
background  process  group  and  is  attempting  to  read  from  its 
controlling  terminal,  and  either  the  process  is  ignoring  or  block¬ 
ing  the  SIGTTIN  signal  or  the  process  group  of  the  process  is 
orphaned.  This  error  may  also  be  generated  when  conditions  | 
unspecified  by  this  part  of  ISO/IEC  9945  occur. 


iso  6.4.1.5  Cross-References 

181  creatO,  5.3.2;  dup(),  6.2.1;  fcntlO,  6.5.2;  IseekO,  6.5.3;  open{),  5.3.1  ;pipe(),  6.1.1; 

182  3.3. 1.4;  7.1.1. 


183  6.4.2  Write  to  a  File 

184  Function:  writei ) 

185  6.4.2.1  Synopsis 

186  ssize_t  write  (int  fildes,  const  void  *buf,  size_t  nbyte)  ; 

187  6.4.2.2  Description 

188  The  write ()  function  shall  attempt  to  write  nbyte  bytes  from  the  buffer  pointed  to 

189  by  buf  to  the  file  associated  with  the  open  file  descriptor,  fildes. 

190  If  nbyte  is  zero  and  the  file  is  a  regular  file,  the  writeO  function  shall  return  zero  | 

191  and  have  no  other  results.  If  nbyte  is  zero  and  the  file  is  not  a  regular  file,  the  | 

192  results  are  unspecified. 

193  On  a  regular  file  or  other  file  capable  of  seeking,  the  actual  writing  of  data  shall 

194  proceed  from  the  position  in  the  file  indicated  by  the  file  offset  associated  with 
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fildes.  Before  successful  return  from  write  (),  the  file  offset  shall  be  incremented 
by  the  number  of  bytes  actually  written.  On  a  regular  file,  if  this  incremented  file 
offset  is  greater  than  the  length  of  the  file,  the  length  of  the  file  shall  be  set  to  this 
file  offset. 

On  a  file  not  capable  of  seeking,  the  write  ()  shall  start  from  the  current  position. 
The  value  of  a  file  offset  associated  with  such  a  file  is  undefined. 

If  the  0_APPEND  flag  of  the  file  status  flags  is  set,  the  file  offset  shall  be  set  to  the 
end  of  the  file  prior  to  each  write,  and  no  intervening  file  modification  operation  | 
shall  be  allowed  between  changing  the  file  offset  and  the  write  operation. 

If  a  write()  requests  that  more  bytes  be  written  than  there  is  room  for  (for  exam¬ 
ple,  the  physical  end  of  a  medium),  only  as  many  bytes  as  there  is  room  for  shall 
be  written.  For  example,  suppose  there  is  space  for  20  bytes  more  in  a  file  before 
reaching  a  limit.  A  write  of  512  bytes  would  return  20.  The  next  write  of  a 
nonzero  number  of  bytes  would  give  a  failure  return  (except  as  noted  below). 

Upon  successful  completion,  the  write{)  function  shall  return  the  number  of  bytes 
actually  written  to  the  file  associated  with  fildes.  This  number  shall  never  be 
greater  than  nbyte . 

If  a  write ()  is  interrupted  by  a  signal  before  it  writes  any  data,  it  shall  return  -1 
with  errno  set  to  [EINTR]. 

If  writei)  is  interrupted  by  a  signal  after  it  successfully  writes  some  data,  either  it 
shall  return  -1  with  errno  set  to  [EINTR),  or  it  shall  return  the  number  of  bytes 
written.  A  writei)  to  a  pipe  or  FIFO  shall  never  return  with  errno  set  to  [EINTR]  if 
it  has  transferred  any  data  and  nbyte  is  less  than  or  equal  to  {PIPE_BUF}. 

If  the  value  of  nbyte  is  greater  than  [SSIZE_MAX],  the  result  is  implementation  | 
defined.  I 

After  a  write ()  to  a  regular  file  has  successfully  returned:  | 

(1)  Any  successful  read()  from  each  byte  position  in  the  file  that  was  | 

modified  by  that  write  ()  shall  return  the  data  specified  by  the  write  ()  for  | 

that  position,  until  such  byte  positions  are  again  modified.  | 

(2)  Any  subsequent  successful  write{)  to  the  same  byte  position  in  the  file  | 

shall  overwrite  that  file  data.  The  phrase  “subsequent  successful  writeiT  \ 
in  the  previous  sentence  is  intended  to  be  viewed  from  a  system  perspec-  | 
tive  [i.e.,  read{)  followed  by  a  systemwide  subsequent  write ()]. 

Write  requests  to  a  pipe  (or  FIFO)  shall  be  handled  in  the  same  manner  as  write  | 
requests  to  a  regular  file,  with  the  following  exceptions:  | 

(1)  There  is  no  file  offset  associated  with  a  pipe,  hence  each  write  request 
shall  append  to  the  end  of  the  pipe. 

(2)  Write  requests  of  {PIPE_BUF}  bytes  or  less  shall  not  be  interleaved  with 
data  from  other  processes  doing  writes  on  the  same  pipe.  Writes  of 
greater  than  {PIPE_BUF}  bytes  may  have  data  interleaved,  on  arbitrary 
boundaries,  with  writes  by  other  processes,  whether  or  not  the 
0_NONBLOCK  flag  of  the  file  status  flags  is  set. 
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(3)  If  the  0_N0NBL0CK  flag  is  clear,  a  write  request  may  cause  the  process 
to  block,  but  on  normal  completion  it  shall  return  nbyte . 

(4)  If  the  0_N0NBL0CK  flag  is  set,  write  ()  requests  shall  be  handled  dif-  | 
ferently,  in  the  following  ways: 

(a)  The  writei)  function  shall  not  block  the  process.  | 

(b)  A  write  request  for  {PIPE_BUF}  or  fewer  bytes  shall  either:  | 

[1]  If  there  is  sufficient  space  available  in  the  pipe,  transfer  all  | 
the  data  and  return  the  number  of  bytes  requested. 

[2]  If  there  is  not  sufficient  space  available  in  the  pipe,  transfer  no  | 

data  and  return  -1  with  errno  set  to  [EAGAIN].  J 

(c)  A  write  request  for  more  than  {PIPE_BUF}  bytes  shall  either:  j 

[1]  When  at  least  one  byte  can  be  written,  transfer  what  it  can  | 

and  return  the  number  of  bytes  written.  When  all  data  previ-  | 
ously  written  to  the  pipe  has  been  read,  it  shall  transfer  at  | 
least  {PIPE_BUF}  bytes.  | 

[2]  When  no  data  can  be  written,  transfer  no  data  and  return  -1  | 

with  errno  set  to  [EAGAIN].  | 

When  attempting  to  write  to  a  file  descriptor  (other  than  a  pipe  or  FIFO)  that  sup¬ 
ports  nonblocking  writes  and  cannot  accept  the  data  immediately: 

(1)  If  the  0_N0NBL0CK  flag  is  clear,  writei)  shall  block  until  the  data  can  be 
accepted. 

(2)  If  the  0_N0NBL0CK  flag  is  set,  writei)  shall  not  block  the  process.  If 
some  data  can  be  written  without  blocking  the  process,  writei)  shall 
write  what  it  can  and  return  the  number  of  bytes  written.  Otherwise,  it 
shall  return  -1  and  errno  shall  be  set  to  [EAGAIN]. 

Upon  successful  completion  where  nbyte  is  greater  than  zero,  the  writei )  function  | 
shall  mark  for  update  the  stjctime  and  stjntime  fields  of  the  file.  | 

G.4.2.3  Returns 

Upon  successful  completion,  writei)  shall  return  an  integer  indicating  the  number 
of  bytes  actually  written.  Otherwise,  it  shall  return  a  value  of  -1  and  set  errno  to 
indicate  the  error. 

6.4.2.4  Errors 

If  any  of  the  following  conditions  occur,  the  writei)  function  shall  return  -1  and 
set  errno  to  the  corresponding  value: 

[EAGAIN]  The  0_N0NBL0CK  flag  is  set  for  the  file  descriptor  and  the  pro¬ 
cess  would  be  delayed  in  the  write  operation. 

[EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor  open  for 
writing. 
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275  [EFBIG]  An  attempt  was  made  to  write  a  file  that  exceeds  an 

276  implementation-defined  maximum  file  size. 


277  [EINTR] 

278 

279 


The  write  operation  was  interrupted  by  a  signal,  and  either  no 
data  was  transferred  or  the  implementation  does  not  report 
partial  transfers  for  this  file. 


280  [EIO] 

281 
282 

283 

284 

285 


The  implementation  supports  job  control,  the  process  is  in  a 
background  process  group  and  is  attempting  to  write  to  its  con¬ 
trolling  terminal,  TOSTOP  is  set,  the  process  is  neither  ignoring 
nor  blocking  SIGTTOU  signals,  and  the  process  group  of  the  pro¬ 
cess  is  orphaned.  This  error  may  also  be  generated  when  condi-  | 
tions  unspecified  by  this  part  of  ISO/IEC  9945  occur. 


286  [ENOSPC]  There  is  no  free  space  remaining  on  the  device  containing  the 

287  file. 


288  [EPIPE] 

289 

290 


An  attempt  is  made  to  write  to  a  pipe  (or  FIFO)  that  is  not  open 
for  reading  by  any  process.  A  SIGPIPE  signal  shall  also  be  sent 
to  the  process. 


291  6.4.2.5  Cross-References 

292  creatO,  5.3.2;  dupO,  6.2.1;  fcntlO,  6.5.2;  Iseek (),  6.5.3;  openO,  5.3.1; pipe (),  6.1.1; 

293  3. 3.1.4. 


294  6.5  Control  Operations  on  Files 

295  6.5.1  Data  Definitions  for  File  Control  Operations 

296  The  header  <fcntl.h>  defines  the  following  requests  and  arguments  for  the 

297  fcntlO  and  openO  functions.  The  values  within  each  of  the  tables  within  this 

298  clause  (Table  6-1  through  Table  6-7)  shall  be  unique  numbers.  In  addition,  the 

299  values  of  the  entries  for  oflag  values,  file  status  flags,  and  file  access  modes  shall 

300  be  unique. 

301  6.5.2  File  Control 

302  Function:  fcntlO 

303  6.5.2.1  Synopsis 

304  #include  <sys/types  . h> 

305  #include  <unistd.h> 

306  #include  <fcntl.h> 

307  int  fcntl(int  fildes ,  int  cmd ,  .  .  .  )  ; 
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Table  6-1  -  cmd  Values  for  fcntl  ( ) 


Constant 

Description 

F_DUPFD 

F_GETFD 

F_GETLK 

F_SETFD 

F_GETFL 

F_SETFL 

F_SETLK 

F_SETLKW 

Duplicate  file  descriptor. 

Get  file  descriptor  flags. 

Get  record  locking  information. 

Set  file  descriptor  flags. 

Get  file  status  flags. 

Set  file  status  flags. 

Set  record  locking  information. 

Set  record  locking  information;  wait  if  blocked. 

Table  6-2  -  File  Descriptor  Flags  Used  for  fcntl  ( ) 

Constant 

Description 

FD_CLOEXEC 

Close  the  file  descriptor  upon  execution  of  an  exec-family 
function. 

Table  6-3 

-  l_type  Values  for  Record  Locking  With  fcntl  () 

Constant 

Description 

F_RDLCK 

F_UNLCK 

F_WRLCK 

Shared  or  read  lock. 

Unlock. 

Exclusive  or  write  lock. 

Table  6-4  -  oflag  Values  for  open  ( ) 

Constant 

Description 

0_CREAT 

0_EXCL 

0_N0CTTY 

0_TRUNC 

Create  file  if  it  does  not  exist. 

Exclusive  use  flag. 

Do  not  assign  a  controlling  terminal. 

Truncate  flag. 

Table  6-5 

-  File  Status  Flags  Used  for  open  ()  and  fcntH ) 

Constant 

Description 

0_APPEND 

0_NONBLOCK 

Set  append  mode. 

No  delay. 
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Table  6-6  -  File  Access  Modes  Used  for  open()  and  fcntlO 


Constant  Description 

OJRDONLY  Open  for  reading  only. 

0_RDWR  Open  for  reading  and  writing. 

0_WRONLY  Open  for  writing  only. 


Table  6-7  -  Mask  for  Use  With  File  Access  Modes 


Constant 


Description 


0_ACCM0DE  Mask  for  file  access  modes. 


6.5.2.2  Description 


The  function  fcntl{)  provides  for  control  over  open  files.  The  argument  fildes  is  a 
file  descriptor. 

The  available  values  for  cmd  are  defined  in  the  header  <fcntl.h>  (see  6.5.1), 
which  shall  include: 


F.DUPFD 


F_GETFD 


F_SETFD 


F_GETFL 


Return  a  new  file  descriptor  that  is  the  lowest  numbered  avail¬ 
able  (i.e.,  not  already  open)  file  descriptor  greater  than  or  equal 
to  the  third  argument,  arg,  taken  as  an  integer  of  type  int.  The 
new  file  descriptor  refers  to  the  same  open  file  description  as 
the  original  file  descriptor  and  shares  any  locks. 

The  FD_CLOEXEC  flag  associated  with  the  new  file  descriptor  is 
cleared  to  keep  the  file  open  across  calls  to  the  exec  family  of 
functions. 

Get  the  file  descriptor  flags,  as  defined  in  Table  6-2,  that  are 
associated  with  the  file  descriptor  fildes.  File  descriptor  flags 
are  associated  with  a  single  file  descriptor  and  do  not  affect 
other  file  descriptors  that  refer  to  the  same  file. 

Set  the  file  descriptor  flags,  as  defined  in  Table  6-2,  that  are 
associated  with  fildes  to  the  third  argument,  arg,  taken  as  type 
int.  If  the  FD_CLOEXEC  flag  is  zero,  the  file  shall  remain  open 
across  exec  functions;  otherwise,  the  file  shall  be  closed  upon 
successful  execution  of  an  exec  function. 

Get  the  file  status  flags,  as  defined  in  Table  6-5,  and  file  access 
modes  for  the  open  file  description  associated  with  fildes.  The 
file  access  modes  defined  in  Table  6-6  can  be  extracted  from  the 
return  value  using  the  mask  O.ACCMODE,  which  is  defined  in 
<f  cntl  .h>.  File  status  flags  and  file  access  modes  are  associ¬ 
ated  with  the  open  file  description  and  do  not  affect  other  file 
descriptors  that  refer  to  the  same  file  with  different  open  file 
descriptions. 
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F_SETFL  Set  the  file  status  flags,  as  defined  in  Table  6-5,  for  the  open  file 
description  associated  with  fildes  from  the  corresponding  bits  in 
the  third  argument,  arg,  taken  as  type  int.  Bits  corresponding 
to  the  file  access  modes  (as  defined  in  Table  6-6)  and  the  oflag 
values  (as  defined  in  Table  6-4)  that  are  set  in  arg  are  ignored. 

If  any  bits  in  arg  other  than  those  mentioned  here  are  changed 
by  the  application,  the  result  is  unspecified. 

The  following  commands  are  available  for  advisory  record  locking.  Advisory 
record  locking  shall  be  supported  for  regular  files,  and  may  be  supported  for  other 
files. 

F_GETLK  Get  the  first  lock  that  blocks  the  lock  description  pointed  to  by 
the  third  argument,  arg ,  taken  as  a  pointer  to  type  struct  flock 
(see  below).  The  information  retrieved  overwrites  the  informa¬ 
tion  passed  to  fcntl( )  in  the  flock  structure.  If  no  lock  is  found 
that  would  prevent  this  lock  from  being  created,  the  structure 
shall  be  left  unchanged  by  this  function  call  except  for  the  lock 
type,  which  shall  be  set  to  FJLJNLCK. 

F_SETLK  Set  or  clear  a  file  segment  lock  according  to  the  lock  description 
pointed  to  by  the  third  argument,  arg,  taken  as  a  pointer  to 
type  struct  flock  (see  below).  F_SETLK  is  used  to  establish 
shared  (or  read)  locks  (F_RDLCK)  or  exclusive  (or  write)  locks, 
(F_WRLCK),  as  well  as  to  remove  either  type  of  lock  (F_UNLCK). 
F.RDLCK,  F_WRLCK,  and  F_UNLCK  are  defined  by  the 
<f  cntl .  h>  header.  If  a  shared  or  exclusive  lock  cannot  be  set, 
fcntl()  shall  return  immediately. 

F_SETLKW  This  command  is  the  same  as  F_SETLK  except  that  if  a  shared 
or  exclusive  lock  is  blocked  by  other  locks,  the  process  shall 
wait  until  the  request  can  be  satisfied.  If  a  signal  that  is  to  be 
caught  is  received  while  fcntl()  is  waiting  for  a  region,  the 
fcntl()  shall  be  interrupted.  Upon  return  from  the  signal 
handler  of  the  process,  fcntli)  shall  return  -1  with  errno  set  to 
[EINTR],  and  the  lock  operation  shall  not  be  done. 

The  flock  structure,  defined  by  the  <f  cntl  .h>  header,  describes  an  advisory  lock. 

It  includes  the  members  shown  in  Table  6-8. 

When  a  shared  lock  has  been  set  on  a  segment  of  a  file,  other  processes  shall  be 
able  to  set  shared  locks  on  that  segment  or  a  portion  of  it.  A  shared  lock  prevents 
any  other  process  from  setting  an  exclusive  lock  on  any  portion  of  the  protected 
area.  A  request  for  a  shared  lock  shall  fail  if  the  file  descriptor  was  not  opened 
with  read  access. 

An  exclusive  lock  shall  prevent  any  other  process  from  setting  a  shared  lock  or  an 
exclusive  lock  on  any  portion  of  the  protected  area.  A  request  for  an  exclusive 
lock  shall  fail  if  the  file  descriptor  was  not  opened  with  write  access. 

The  value  of  l_whence  is  SEEK_SET,  SEEK_CUR,  or  SEEK_END  to  indicate  that 
the  relative  offset,  l_start  bytes,  will  be  measured  from  the  start  of  the  file, 
current  position,  or  end  of  the  file,  respectively.  The  value  of  l_len  is  the  number 
of  consecutive  bytes  to  be  locked.  If  l_len  is  negative,  the  result  is  undefined.  The  | 
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Table  6-8  -  flock  Structure 


Member 

Type 

Member 

Name 

Description 

short 

Ijype 

F_RDLCK,  F_WRLCK,  or  FJJNLCK. 

short 

Ijuuhence 

Flag  for  starting  offset. 

offj 

Ijstart 

Relative  offset  in  bytes. 

offj 

l_len 

Size;  if  0,  then  until  EOF. 

pid_t 

l  _pid 

Process  ID  of  the  process  holding  the  lock,  returned  with  F_GETLK. 

l _pid  field  is  only  used  with  F_GETLK  to  return  the  process  ID  of  the  process  hold¬ 
ing  a  blocking  lock.  After  a  successful  F_GETLK  request,  the  value  of  Ijuuhence 
shall  be  SEEKJ3ET. 

Locks  may  start  and  extend  beyond  the  current  end  of  a  file,  but  shall  not  start  or 
extend  before  the  beginning  of  the  file.  A  lock  shall  be  set  to  extend  to  the  largest 
possible  value  of  the  file  offset  for  that  file  if  l_len  is  set  to  zero.  If  the  flock  struct 
has  Ijuuhence  and  l_start  that  point  to  the  beginning  of  the  file,  and  l_len  of  zero, 
the  entire  file  shall  be  locked. 

There  shall  be  at  most  one  type  of  lock  set  for  each  byte  in  the  file.  Before  a  suc¬ 
cessful  return  from  an  F_SETLK  or  an  F_SETLKW  request  when  the  calling  pro¬ 
cess  has  previously  existing  locks  on  bytes  in  the  region  specified  by  the  request, 
the  previous  lock  type  for  each  byte  in  the  specified  region  shall  be  replaced  by  the 
new  lock  type.  As  specified  above  under  the  descriptions  of  shared  locks  and 
exclusive  locks,  an  F_SETLK  or  an  F_SETLKW  request  shall  (respectively)  fail  or 
block  when  another  process  has  existing  locks  on  bytes  in  the  specified  region  and 
the  type  of  any  of  those  locks  conflicts  with  the  type  specified  in  the  request. 

All  locks  associated  with  a  file  for  a  given  process  shall  be  removed  when  a  file 
descriptor  for  that  file  is  closed  by  that  process  or  the  process  holding  that  file 
descriptor  terminates.  Locks  are  not  inherited  by  a  child  process  created  using 
the  fork ()  function. 

A  potential  for  deadlock  occurs  if  a  process  controlling  a  locked  region  is  put  to 
sleep  by  attempting  to  lock  the  locked  region  of  another  process.  If  the  system 
detects  that  sleeping  until  a  locked  region  is  unlocked  would  cause  a  deadlock,  the 
fcntli)  function  shall  fail  with  an  [EDEADLK]  error. 

6.5.2.3  Returns 

Upon  successful  completion,  the  value  returned  shall  depend  on  cmd.  The  vari¬ 
ous  return  values  are  shown  in  Table  6-9. 

Otherwise,  a  value  of  -1  shall  be  returned  and  errno  shall  be  set  to  indicate  the 
error. 


6.5  Control  Operations  on  Files 


125 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


INFORMATION  TECHNOLOGY— POSIX 


474 

475 

Table  6-9  -  fcntl  ( )  Return  Values 

476 

Request 

Return  Value 

477 

F_DUPFD 

A  new  file  descriptor. 

478 

F_GETFD 

Value  of  the  flags  defined  in  Table  6-2,  but  the  return  value  shall  not  be  negative. 

479 

F_SETFD 

Value  other  than  -1. 

480 

F_GETFL 

Value  of  file  status  flags  and  access  modes,  but  the  return  value  shall  not  be  negative. 

481 

F_SETFL 

Value  other  than  -1. 

482 

F_GETLK 

Value  other  than  -1. 

483 

F_SETLK 

Value  other  than  -1. 

484 

F_SETLKW 

Value  other  than  -1. 

485 

486  6.5.2.4  Errors 


487  If  any  of  the  following  conditions  occur,  the  fcntl{ )  function  shall  return  -1  and  set 

488  errno  to  the  corresponding  value: 


489 

490 

491 

492 

493 

494 

495 


[EACCES]  or  [EAGAIN] 

The  argument  cmd  is  F_SETLK,  the  type  of  lock  ( l_type )  is  a 
shared  lock  (F_RDLCK)  or  exclusive  lock  (F_WRLCK),  and  the 
segment  of  a  file  to  be  locked  is  already  exclusive-locked  by 
another  process;  or  the  type  is  an  exclusive  lock  and  some  por¬ 
tion  of  the  segment  of  a  file  to  be  locked  is  already  shared- 
locked  or  exclusive-locked  by  another  process. 


496  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 


497 

498 

499 


The  argument  cmd  is  F_SETLK  or  F_SETLKW,  the  type  of  lock 
( Ijype )  is  a  shared  lock  (F_RDLCK),  and  fildes  is  not  a  valid  file 
descriptor  open  for  reading. 


500 

501 

502 


The  argument  cmd  is  F_SETLK  or  F_SETLKW,  the  type  of  lock 
(I  Jype )  is  an  exclusive  lock  (F_WRLCK),  and  fildes  is  not  a  valid 
file  descriptor  open  for  writing. 


503  [EINTRl  The  argument  cmd  is  F_SETLKW,  and  the  function  was  inter- 

504  rupted  by  a  signal. 


505  [EINVAL]  The  argument  cmd  is  F_DUPFD,  and  the  third  argument  is 

506  negative  or  greater  than  or  equal  to  {OPEN_MAX}. 


507 

508 

509 


The  argument  cmd  is  F_GETLK,  F_SETLK,  or  FJ3ETLKW  and 
the  data  to  which  arg  points  is  not  valid,  or  fildes  refers  to  a  file 
that  does  not  support  locking. 


510 

511 

512 


[EMFILE]  The  argument  cmd  is  F_DUPFD  and  {OPEN_MAX}  file  descrip¬ 
tors  are  currently  in  use  by  this  process,  or  no  file  descriptors 
greater  than  or  equal  to  arg  are  available. 


513 

514 

515 


[ENOLCK]  The  argument  cmd  is  F_SETLK  or  F_SETLKW,  and  satisfying 
the  lock  or  unlock  request  would  result  in  the  number  of  locked 
regions  in  the  system  exceeding  a  system-imposed  limit. 
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516  For  each  of  the  following  conditions,  if  the  condition  is  detected,  the  fcntl ()  func- 

517  tion  shall  return  -1  and  set  errno  to  the  corresponding  value: 

518  [EDEADLK]  The  argument  cmd  is  F_SETLKW,  and  a  deadlock  condition  was 

519  detected. 

520  6.5.2.5  Cross-References 

521  close (),  6.3.1;  exec,  3.1.2;  openi),  5.3.1;  <f  cntl .  h>,  6.5.1;  3.3.I.4. 


522  6.5.3  Reposition  Read/Write  File  Offset 

523  Function:  Iseeki) 


524  6.5.3. 1  Synopsis 

525  #include  <sys/types  .  h> 

526  #include  <unistd.h> 

527  off_t  lseek(int  fildes,  off_t  offset,  int  whence); 


528  6.5.3.2  Description 


529  The  fildes  argument  is  an  open  file  descriptor.  The  Iseek  ()  function  shall  set  the 

530  file  offset  for  the  open  file  description  associated  with  fildes  as  follows: 


531 

532 

533 


(1)  If  whence  is  SEEK_SET,  the  offset  is  set  to  offset  bytes. 

(2)  If  whence  is  SEEK_CUR,  the  offset  is  set  to  its  current  value  plus  offset 
bytes. 


534  (3)  If  whence  is  SEEK_END,  the  offset  is  set  to  the  size  of  the  file  plus  offset 

535  bytes. 


536  The  symbolic  constants  SEEK_SET,  SEEK_CUR,  and  SEEK_END  are  defined  in  the 

537  header  cunistd .  h>. 


538  Some  devices  are  incapable  of  seeking.  The  value  of  the  file  offset  associated  with 

539  such  a  device  is  undefined.  The  behavior  of  the  Iseeki.)  function  on  such  devices  is 

540  implementation  defined. 

541  The  Iseeki)  function  shall  allow  the  file  offset  to  be  set  beyond  the  end  of  existing 

542  data  in  the  file.  If  data  is  later  written  at  this  point,  subsequent  reads  of  data  in 

543  the  gap  shall  return  bytes  with  the  value  zero  until  data  is  actually  written  into 

544  the  gap. 

545  The  Iseeki)  function  shall  not,  by  itself,  extend  the  size  of  a  file. 


546  6.5.3.3  Returns 

547  Upon  successful  completion,  the  function  shall  return  the  resulting  offset  location 

548  as  measured  in  bytes  from  the  beginning  of  the  file.  Otherwise,  it  shall  return  a 

549  value  of  iioffj)  -1),  shall  set  errno  to  indicate  the  error,  and  the  file  offset  shall 

550  remain  unchanged  by  this  function  call. 
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551  6.5.3.4  Errors 


552  If  any  of  the  following  conditions  occur,  the  Iseek  ()  function  shall  return  -1  and 

553  set  errno  to  the  corresponding  value: 

554  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

555  [EINVAL]  The  whence  argument  is  not  a  proper  value,  or  the  resulting  file 

556  offset  would  be  invalid. 


557  [ESPIPE]  The  fildes  argument  is  associated  with  a  pipe  or  FIFO. 


558  6.5.3.5  Cross-References 

559  creat{),  5.3.2;  dup (),  6.2.1;  fcntlO,  6.5.2;  open(),  5.3.1;  read(),  6.4.1;  sigactioni), 

560  3.3.4;  write(),  6.4.2;  <unistd.h>,  2.9. 
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Section  7:  Device-  and  Class-Specific  Functions 


1  7.1  General  Terminal  Interface 

2  This  section  describes  a  general  terminal  interface  that  shall  be  provided.  It  shall  | 

3  be  supported  on  any  asynchronous  communication  ports  if  the  implementation  | 

4  provides  them.  It  is  implementation  defined  whether  this  interface  supports  net-  | 

5  work  connections  or  synchronous  ports  or  both.  The  conformance  document  shall  | 

6  describe  which  device  types  are  supported  by  these  interfaces.  Certain  functions  | 

7  in  this  section  apply  only  to  the  controlling  terminal  of  a  process;  where  this  is  the  | 

8  case,  it  is  so  noted. 

9  7.1.1  Interface  Characteristics 

10  7.1. 1.1  Opening  a  Terminal  Device  File 

n  When  a  terminal  file  is  opened,  it  normally  causes  the  process  to  wait  until  a  con- 

12  nection  is  established.  In  practice,  application  programs  seldom  open  these  files; 

13  they  are  opened  by  special  programs  and  become  the  standard  input,  output,  and 

14  error  files  of  an  application. 

15  As  described  in  5.3.1,  opening  a  terminal  device  file  with  the  0_NONBLOCK  flag 

16  clear  shall  cause  the  process  to  block  until  the  terminal  device  is  ready  and  avail- 

17  able.  The  CLOCAL  flag  can  also  affect  open().  See  7.I.2.4. 

is  7.1. 1.2  Process  Groups 

19  A  terminal  may  have  a  foreground  process  group  associated  with  it.  This  fore- 

20  ground  process  group  plays  a  special  role  in  handling  signal-generating  input 

21  characters,  as  discussed  below  in  7. 1.1.9. 

22  If  the  implementation  supports  job  control  (if  LPOSIX_JOB_CONTROL}  is  defined; 

23  see  2.9),  command  interpreter  processes  supporting  job  control  can  allocate  the 

24  terminal  to  different  jobs,  or  process  groups,  by  placing  related  processes  in  a  sin- 

25  gle  process  group  and  associating  this  process  group  with  the  terminal.  The  fore- 

26  ground  process  group  of  a  terminal  may  be  set  or  examined  by  a  process,  assum- 

27  ing  the  permission  requirements  in  this  section  are  met;  see  7.2.3  and  7.2.4.  The 

28  terminal  interface  aids  in  this  allocation  by  restricting  access  to  the  terminal  by 

29  processes  that  are  not  in  the  foreground  process  group;  see  7. 1.1.4. 

30  When  there  is  no  longer  any  process  whose  process  ID  or  process  group  ID  | 

31  matches  the  process  group  ID  of  the  foreground  process  group,  the  terminal  shall  | 

32  have  no  foreground  process  group.  It  is  unspecified  whether  the  terminal  has  a  | 

33  foreground  process  group  when  there  is  no  longer  any  process  whose  process  | 
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group  ID  matches  the  process  group  ID  of  the  foreground  process  group,  but  there 
is  a  process  whose  process  ID  matches.  No  actions  defined  by  this  part  of 
ISO/IEC  9945,  other  than  allocation  of  a  controlling  terminal  as  described  in 

7. 1.1.3  or  a  successful  call  to  tcsetpgrpi) ,  shall  cause  a  process  group  to  become 
the  foreground  process  group  of  a  terminal. 

7. 1.1. 3  The  Controlling  Terminal 

A  terminal  may  belong  to  a  process  as  its  controlling  terminal.  Each  process  of  a 
session  that  has  a  controlling  terminal  has  the  same  controlling  terminal.  A  ter¬ 
minal  may  be  the  controlling  terminal  for  at  most  one  session.  The  controlling 
terminal  for  a  session  is  allocated  by  the  session  leader  in  an  implementation- 
defined  manner.  If  a  session  leader  has  no  controlling  terminal  and  opens  a  ter¬ 
minal  device  file  that  is  not  already  associated  with  a  session  without  using  the 
0_NOCTTY  option  (see  5.3.1),  it  is  implementation  defined  whether  the  terminal 
becomes  the  controlling  terminal  of  the  session  leader.  If  a  process  that  is  not  a 
session  leader  opens  a  terminal  file,  or  the  0_NOCTTY  option  is  used  on  open  (), 
that  terminal  shall  not  become  the  controlling  terminal  of  the  calling  process. 
When  a  controlling  terminal  becomes  associated  with  a  session,  its  foreground 
process  group  shall  be  set  to  the  process  group  of  the  session  leader. 

The  controlling  terminal  is  inherited  by  a  child  process  during  a  fork{ )  function 
call.  A  process  relinquishes  its  controlling  terminal  when  it  creates  a  new  session 
with  the  setsidO  function;  other  processes  remaining  in  the  old  session  that  had 
this  terminal  as  their  controlling  terminal  continue  to  have  it.  Upon  the  close  of 
the  last  file  descriptor  in  the  system  (whether  or  not  it  is  in  the  current  session) 
associated  with  the  controlling  terminal,  it  is  unspecified  whether  all  processes 
that  had  that  terminal  as  their  controlling  terminal  cease  to  have  any  controlling 
terminal.  Whether  and  how  a  session  leader  can  reacquire  a  controlling  terminal 
after  the  controlling  terminal  has  been  relinquished  in  this  fashion  is  unspecified. 
A  process  does  not  relinquish  its  controlling  terminal  simply  by  closing  all  of  its 
file  descriptors  associated  with  the  controlling  terminal  if  other  processes  con¬ 
tinue  to  have  it  open. 

When  a  controlling  process  terminates,  the  controlling  terminal  is  disassociated 
from  the  current  session,  allowing  it  to  be  acquired  by  a  new  session  leader.  Sub¬ 
sequent  access  to  the  terminal  by  other  processes  in  the  earlier  session  may  be 
denied,  with  attempts  to  access  the  terminal  treated  as  if  modem  disconnect  had 
been  sensed. 

7.1. 1.4  Terminal  Access  Control 

If  a  process  is  in  the  foreground  process  group  of  its  controlling  terminal,  read 
operations  shall  be  allowed  as  described  in  7. 1.1.5.  For  those  implementations 
that  support  job  control,  any  attempts  by  a  process  in  a  background  process  group 
to  read  from  its  controlling  terminal  shall  cause  its  process  group  to  be  sent  a 
SIGTTIN  signal  unless  one  of  the  following  special  cases  apply:  If  the  reading  pro¬ 
cess  is  ignoring  or  blocking  the  SIGTTIN  signal,  or  if  the  process  group  of  the  read¬ 
ing  process  is  orphaned,  the  read{)  returns  -1  with  errno  set  to  [EIO],  and  no  sig¬ 
nal  is  sent.  The  default  action  of  the  SIGTTIN  signal  is  to  stop  the  process  to 
which  it  is  sent.  See  3.3.1. 1. 
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If  a  process  is  in  the  foreground  process  group  of  its  controlling  terminal,  write 
operations  shall  be  allowed  as  described  in  7. 1.1. 8.  Attempts  by  a  process  in  a 
background  process  group  to  write  to  its  controlling  terminal  shall  cause  the  pro¬ 
cess  group  to  be  sent  a  SIGTTOU  signal  unless  one  of  the  following  special  cases 
apply:  If  TOSTOP  is  not  set,  or  if  TOSTOP  is  set  and  the  process  is  ignoring  or 
blocking  the  SIGTTOU  signal,  the  process  is  allowed  to  write  to  the  terminal  and 
the  SIGTTOU  signal  is  not  sent.  If  TOSTOP  is  set,  and  the  process  group  of  the 
writing  process  is  orphaned,  and  the  writing  process  is  not  ignoring  or  blocking 
SIGTTOU,  the  write()  returns  -1  with  errno  set  to  [EIO],  and  no  signal  is  sent. 

Certain  calls  that  set  terminal  parameters  are  treated  in  the  same  fashion  as 
write,  except  that  TOSTOP  is  ignored;  that  is,  the  effect  is  identical  to  that  of  ter¬ 
minal  writes  when  TOSTOP  is  set.  See  7.2. 

7.1. 1.5  Input  Processing  and  Reading  Data 

A  terminal  device  associated  with  a  terminal  device  file  may  operate  in  full- 
duplex  mode,  so  that  data  may  arrive  even  while  output  is  occurring.  Each  termi¬ 
nal  device  file  has  associated  with  it  an  input  queue,  into  which  incoming  data  is 
stored  by  the  system  before  being  read  by  a  process.  The  system  may  impose  a 
limit,  {MAX_INPUT},  on  the  number  of  bytes  that  may  be  stored  in  the  input 
queue.  The  behavior  of  the  system  when  this  limit  is  exceeded  is  implementation 
defined. 

Two  general  kinds  of  input  processing  are  available,  determined  by  whether  the 
terminal  device  file  is  in  canonical  mode  or  noncanonical  mode.  These  modes  are 
described  in  7.1. 1.6  and  7.1. 1.7.  Additionally,  input  characters  are  processed 
according  to  the  cjiflag  (see  7. 1.2.2)  and  c_lflag  (see  7.1. 2. 5)  fields.  Such  process¬ 
ing  can  include  echoing,  which  in  general  means  transmitting  input  characters 
immediately  back  to  the  terminal  when  they  are  received  from  the  terminal.  This 
is  useful  for  terminals  that  can  operate  in  full-duplex  mode. 

The  manner  in  which  data  is  provided  to  a  process  reading  from  a  terminal  device 
file  is  dependent  on  whether  the  terminal  device  file  is  in  canonical  or  noncanoni¬ 
cal  mode. 

Another  dependency  is  whether  the  0_NONBLOCK  flag  is  set  by  open{)  or  fcntl{). 
If  the  0_NONBLOCK  flag  is  clear,  then  the  read  request  shall  be  blocked  until 
data  is  available  or  a  signal  has  been  received.  If  the  0_NONBLOCK  flag  is  set, 
then  the  read  request  shall  be  completed,  without  blocking,  in  one  of  three  ways: 

(1)  If  there  is  enough  data  available  to  satisfy  the  entire  request,  the  read() 
shall  complete  successfully  and  return  the  number  of  bytes  read. 

(2)  If  there  is  not  enough  data  available  to  satisfy  the  entire  request,  the 
read()  shall  complete  successfully,  having  read  as  much  data  as  possible, 
and  return  the  number  of  bytes  it  was  able  to  read. 

(3)  If  there  is  no  data  available,  the  read{)  shall  return  -1  with  errno  set  to 
[EAGAIN]. 

When  data  is  available  depends  on  whether  the  input  processing  mode  is  canoni¬ 
cal  or  noncanonical.  The  following  subclauses,  7. 1.1. 6  and  7. 1.1. 7,  describe  each 
of  these  input  processing  modes. 
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7. 1.1.6  Canonical  Mode  Input  Processing 

In  canonical  mode  input  processing,  terminal  input  is  processed  in  units  of  lines. 

A  line  is  delimited  by  a  newline  ('\n')  character,  an  end-of-file  (EOF)  character,  or  | 
an  end-of-line  (EOL)  character.  See  7.1. 1.9  for  more  information  on  EOF  and  EOL. 
This  means  that  a  read  request  shall  not  return  until  an  entire  line  has  been 
typed  or  a  signal  has  been  received.  Also,  no  matter  how  many  bytes  are 
requested  in  the  read  call,  at  most  one  line  shall  be  returned.  It  is  not,  however, 
necessary  to  read  a  whole  line  at  once;  any  number  of  bytes,  even  one,  may  be 
requested  in  a  read  without  losing  information. 

If  {MAX_CANON}  is  defined  for  this  terminal  device,  it  is  a  limit  on  the  number  of 
bytes  in  a  fine.  The  behavior  of  the  system  when  this  limit  is  exceeded  is  imple¬ 
mentation  defined.  If  {MAX_CANON}  is  not  defined,  there  is  no  such  limit; 
see  2.8.5. 

Erase  and  kill  processing  occur  when  either  of  two  special  characters,  the  ERASE 
and  KILL  characters  (see  7. 1.1.9),  is  received.  This  processing  affects  data  in  the 
input  queue  that  has  not  yet  been  delimited  by  a  newline  (NL),  EOF,  or  EOL  char¬ 
acter.  This  undelimited  data  makes  up  the  current  line.  The  ERASE  character 
deletes  the  last  character  in  the  current  line,  if  there  is  any.  The  KILL  character 
deletes  all  data  in  the  current  line,  if  there  is  any.  The  ERASE  and  KILL  charac¬ 
ters  have  no  effect  if  there  is  no  data  in  the  current  line.  The  ERASE  and  KILL 
characters  themselves  are  not  placed  in  the  input  queue. 

7.1. 1.7  Noncanonical  Mode  Input  Processing 

In  noncanonical  mode  input  processing,  input  bytes  are  not  assembled  into  lines, 
and  erase  and  kill  processing  does  not  occur.  The  values  of  the  MIN  and  TIME 
members  of  the  c_cc  array  are  used  to  determine  how  to  process  the  bytes 
received. 

MIN  represents  the  minimum  number  of  bytes  that  should  be  received  when  the 
read()  function  successfully  returns.  TIME  is  a  timer  of  0,1  second  granularity 
that  is  used  to  time  out  short-term  or  bursty  data  transmissions.  If  MIN  is 
greater  than  {MAX_INPUT},  the  response  to  the  request  is  undefined.  The  four  | 
possible  values  for  MIN  and  TIME  and  their  interactions  are  described  below. 

7.1. 1.7.1  Case  A:  MIN  >  0,  TIME  >  0 

In  this  case  TIME  serves  as  an  interbyte  timer  and  is  activated  after  the  first  byte 
is  received.  Since  it  is  an  interbyte  timer,  it  is  reset  after  a  byte  is  received.  The 
interaction  between  MIN  and  TIME  is  as  follows:  as  soon  as  one  byte  is  received, 
the  interbyte  timer  is  started.  If  MIN  bytes  are  received  before  the  interbyte  timer 
expires  (remember  that  the  timer  is  reset  upon  receipt  of  each  byte),  the  read  is 
satisfied.  If  the  timer  expires  before  MIN  bytes  are  received,  the  characters 
received  to  that  point  are  returned  to  the  user.  Note  that  if  TIME  expires,  at  least 
one  byte  shall  be  returned  because  the  timer  would  not  have  been  enabled  unless 
a  byte  was  received.  In  this  case  (MIN  >  0,  TIME  >  0),  the  read  shall  block  until 
the  MIN  and  TIME  mechanisms  are  activated  by  the  receipt  of  the  first  byte  or 
until  a  signal  is  received.  If  data  is  in  the  buffer  at  the  time  of  the  read (),  the  | 
result  shall  be  as  if  data  had  been  received  immediately  after  the  read(). 
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7.1. 1.7.2  Case  B:  MIN  >  0,  TIME  =  0 

In  this  case,  since  the  value  of  TIME  is  zero,  the  timer  plays  no  role  and  only  MIN 
is  significant.  A  pending  read  is  not  satisfied  until  MIN  bytes  are  received  (i.e., 
the  pending  read  shall  block  until  MIN  bytes  are  received)  or  a  signal  is  received. 

A  program  that  uses  this  case  to  read  record-based  terminal  I/O  may  block 
indefinitely  in  the  read  operation. 

7.1. 1.7.3  Case  C:  MIN  =  0,  TIME  >  0 

In  this  case,  since  MIN  =  0,  TIME  no  longer  represents  an  interbyte  timer.  It  now 
serves  as  a  read  timer  that  is  activated  as  soon  as  the  read()  function  is  pro¬ 
cessed.  A  read  is  satisfied  as  soon  as  a  single  byte  is  received  or  the  read  timer 
expires.  Note  that  in  this  case  if  the  timer  expires,  no  bytes  shall  be  returned.  If 
the  timer  does  not  expire,  the  only  way  the  read  can  be  satisfied  is  if  a  byte  is 
received.  In  this  case,  the  read  shall  not  block  indefinitely  waiting  for  a  byte;  if  no 
byte  is  received  within  TIME*0,1  seconds  after  the  read  is  initiated,  the  read() 
shall  return  a  value  of  zero,  having  read  no  data.  If  data  is  in  the  buffer  at  the  | 
time  of  the  read (),  the  timer  shall  be  started  as  if  data  had  been  received  immedi-  | 
ately  after  the  read{).  \ 

7.1. 1.7.4  Case  D:  MIN  =  0,  TIME  =  0 

The  minimum  of  either  the  number  of  bytes  requested  or  the  number  of  bytes 
currently  available  shall  be  returned  without  waiting  for  more  bytes  to  be  input. 

If  no  characters  are  available,  readO  shall  return  a  value  of  zero,  having  read  no 
data. 

7.1. 1.8  Writing  Data  and  Output  Processing 

When  a  process  writes  one  or  more  bytes  to  a  terminal  device  file,  they  are  pro¬ 
cessed  according  to  the  c_oflag  field  (see  7. 1.2.3).  The  implementation  may  pro¬ 
vide  a  buffering  mechanism;  as  such,  when  a  call  to  writeO  completes,  all  of  the 
bytes  written  have  been  scheduled  for  transmission  to  the  device,  but  the 
transmission  will  not  necessarily  have  completed.  See  also  6.4.2  for  the  effects  of 
O.NONBLOCK on  write(). 

7. 1.1. 9  Special  Characters 

Certain  characters  have  special  functions  on  input  or  output  or  both.  These  func¬ 
tions  are  summarized  as  follows: 

INTR  Special  character  on  input  and  recognized  if  the  ISIG  flag  (see 

7. 1.2.5)  is  enabled.  It  generates  a  SIGINT  signal  that  is  sent  to 
all  processes  in  the  foreground  process  group  for  which  the  ter¬ 
minal  is  the  controlling  terminal.  If  ISIG  is  set,  the  INTR  char¬ 
acter  is  discarded  when  processed. 

QUIT  Special  character  on  input  and  recognized  if  the  ISIG  flag  is 

enabled.  It  generates  a  SIGQUIT  signal  that  is  sent  to  all 
processes  in  the  foreground  process  group  for  which  the  termi¬ 
nal  is  the  controlling  terminal.  If  ISIG  is  set,  the  QUIT  charac¬ 
ter  is  discarded  when  processed. 
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ERASE 


KILL 


EOF 


NL 

EOL 

SUSP 


STOP 


START 


CR 


Special  character  on  input  and  recognized  if  the  ICANON  flag  is 
set.  It  erases  the  last  character  in  the  current  line;  see  7. 1.1. 6. 
The  ERASE  character  shall  not  erase  beyond  the  start  of  a  line, 
as  delimited  by  an  NL,  EOF,  or  EOL  character.  If  ICANON  is 
set,  the  ERASE  character  is  discarded  when  processed. 

Special  character  on  input  and  recognized  if  the  ICANON  flag  is 
set.  It  deletes  the  entire  line,  as  delimited  by  a  NL,  EOF,  or 
EOL  character.  If  ICANON  is  set,  the  KILL  character  is  dis¬ 
carded  when  processed. 

Special  character  on  input  and  recognized  if  the  ICANON  flag  is 
set.  When  received,  all  the  bytes  waiting  to  be  read  are 
immediately  passed  to  the  process,  without  waiting  for  a  new- 
line,  and  the  EOF  is  discarded.  Thus,  if  there  are  no  bytes  wait¬ 
ing  (that  is,  the  EOF  occurred  at  the  beginning  of  a  line),  a  byte 
count  of  zero  shall  be  returned  from  the  read(),  representing  an 
end-of-file  indication.  If  ICANON  is  set,  the  EOF  character  is 
discarded  when  processed. 

Special  character  on  input  and  recognized  if  the  ICANON  flag  is 
set.  It  is  the  line  delimiter  ('\n'). 

Special  character  on  input  and  recognized  if  the  ICANON  flag  is 
set.  It  is  an  additional  line  delimiter,  like  NL. 

Recognized  on  input  if  job  control  is  supported  (see  7.1. 2. 6).  If 
the  ISIG  flag  is  enabled,  receipt  of  the  SUSP  character  causes  a 
SIGTSTP  signal  to  be  sent  to  all  processes  in  the  foreground  pro¬ 
cess  group  for  which  the  terminal  is  the  controlling  terminal, 
and  the  SUSP  character  is  discarded  when  processed. 

Special  character  on  both  input  and  output  and  recognized  if 
the  IXON  (output  control)  or  IXOFF  (input  control)  flag  is  set.  It 
can  be  used  to  temporarily  suspend  output.  It  is  useful  with 
CRT  terminals  to  prevent  output  from  disappearing  before  it 
can  be  read.  If  IXON  is  set,  the  STOP  character  is  discarded 
when  processed. 

Special  character  on  both  input  and  output  and  recognized  if 
the  IXON  (output  control)  or  IXOFF  (input  control)  flag  is  set. 
Can  be  used  to  resume  output  that  has  been  suspended  by  a 
STOP  character.  If  IXON  is  set,  the  START  character  is  dis¬ 
carded  when  processed. 

Special  character  on  input  and  recognized  if  the  ICANON  flag  is 
set;  it  is  the  '\r',  as  denoted  in  the  C  Standard  {2}.  When  | 
ICANON  and  ICRNL  are  set  and  IGNCR  is  not  set,  this  character 
is  translated  into  a  NL  and  has  the  same  effect  as  a  NL 
character. 


The  NL  and  CR  characters  cannot  be  changed.  It  is  implementation  defined 
whether  the  START  and  STOP  characters  can  be  changed.  The  values  for  INTR, 
QUIT,  ERASE,  KILL,  EOF,  EOL,  and  SUSP  (job  control  only),  shall  be  changeable  to 
suit  individual  tastes. 
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255  If  LPOSIX_VDISABLE}  is  in  effect  for  the  terminal  file,  special  character  functions 

256  associated  with  changeable  special  control  characters  can  be  disabled  individu- 

257  ally;  see  7. 1.2.6. 

258  If  two  or  more  special  characters  have  the  same  value,  the  function  performed 

259  when  that  character  is  received  is  undefined. 

260  A  special  character  is  recognized  not  only  by  its  value,  but  also  by  its  context;  for 

261  example,  an  implementation  may  define  multibyte  sequences  that  have  a  mean- 

262  ing  different  from  the  meaning  of  the  bytes  when  considered  individually.  Imple- 

263  mentations  may  also  define  additional  single-byte  functions.  These 

264  implementation- defined  multibyte  or  single-byte  functions  are  recognized  only  if 

265  the  IEXTEN  flag  is  set;  otherwise,  data  is  received  without  interpretation,  except  | 

266  as  required  to  recognize  the  special  characters  defined  in  this  subclause  (7. 1.1.9). 

267  7.1.1.10  Modem  Disconnect 

268  If  a  modem  disconnect  is  detected  by  the  terminal  interface  for  a  controlling  ter- 

269  minal,  and  if  CLOCAL  is  not  set  in  the  cjcflag  field  for  the  terminal  (see  7. 1.2.4), 

270  the  SIGHUP  signal  is  sent  to  the  controlling  process  associated  with  the  terminal. 

271  Unless  other  arrangements  have  been  made,  this  causes  the  controlling  process  to 

272  terminate;  see  3.2.2.  Any  subsequent  call  to  the  read ()  function  shall  return  the  | 

273  value  zero,  indicating  end  of  file.  See  6.4.1.  Thus,  processes  that  read  a  terminal  | 

274  file  and  test  for  end-of-file  can  terminate  appropriately  after  a  disconnect.  If  the  | 

275  [EIO]  condition  specified  in  6.4. 1.4  that  applies  when  the  implementation  supports  | 

276  job  control  also  exists,  it  is  unspecified  whether  the  EOF  condition  or  the  [EIO]  is  | 

277  returned.  Any  subsequent  write()  to  the  terminal  device  returns  -1,  with  errno  | 

278  set  to  [EIO],  until  the  device  is  closed. 

279  7.1.1.11  Closing  a  Terminal  Device  File 

280  The  last  process  to  close  a  terminal  device  file  shall  cause  any  output  to  be  sent  to 

281  the  device  and  any  input  to  be  discarded.  Then,  if  HUPCL  is  set  in  the  control 

282  modes  and  the  communications  port  supports  a  disconnect  function,  the  terminal 

283  device  shall  perform  a  disconnect. 

284  7.1.2  Parameters  That  Can  Be  Set  I 

285  7. 1.2.1  termios  Structure 

286  Routines  that  need  to  control  certain  terminal  I/O  characteristics  shall  do  so  by 

287  using  the  termios  structure  as  defined  in  the  header  <termios.h>.  The 

288  members  of  this  structure  include  (but  are  not  limited  to)  those  shown  in  Table  7- 

289  1. 

290  The  types  tcflagj  and  cc_t  shall  be  defined  in  the  header  <termios  .h>.  They 

291  shall  be  unsigned  integral  types. 

292 
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293  Table  7-1  -  termios  Structure  | 

294  _ _  _ _ 


295 

296 

Member 

Type 

Array  Member  „  .  . . 

c,.  XT  Description 

Size  Name 

297 

tcflagj 

cjflag  Input  modes. 

298 

tcflagjt 

c_oflag  Output  modes. 

299 

tcflagj 

c_cflag  Control  modes. 

300 

tcflagj 

cjflag  Local  modes. 

301 

ccj 

NCCS  c_cc  Control  characters. 

302 

303 

7. 1.2.2  Input  Modes 

304 

Values  of  the  cjflag  field,  shown  in  Table  7-2,  describe  the  basic  terminal  input 

305 

control  and  are  composed  of  the  bitwise  inclusive  OR  of  the  masks  shown,  which 

306 

shall  be  bitwise  distinct. 

The  mask  name  symbols  in  this  table  are  defined  in 

307 

<termios . h>. 

308 

Table  7-2  -  termios  cjflag  Field 

309 

310 

Mask  Name  Description 

311 

BRKINT 

Signal  interrupt  on  break. 

312 

ICRNL 

Map  CR  to  NL  on  input. 

313 

IGNBRK 

Ignore  break  condition. 

314 

IGNCR 

Ignore  CR. 

315 

IGNPAR 

Ignore  characters  with  parity  errors. 

316 

ENLCR 

Map  NL  to  CR  on  input. 

317 

ENPCK 

Enable  input  parity  check. 

318 

ISTRIP 

Strip  character. 

319 

IXOFF 

Enable  start/stop  input  control. 

320 

IXON 

Enable  start/stop  output  control. 

321 

PARMRK 

Mark  parity  errors. 

322 

323  In  the  context  of  asynchronous  serial  data  transmission,  a  break  condition  is 

324  defined  as  a  sequence  of  zero-valued  bits  that  continues  for  more  than  the  time  to 

325  send  one  byte.  The  entire  sequence  of  zero-valued  bits  is  interpreted  as  a  single 

326  break  condition,  even  if  it  continues  for  a  time  equivalent  to  more  than  one  byte. 

327  In  contexts  other  than  asynchronous  serial  data  transmission,  the  definition  of  a 

328  break  condition  is  implementation  defined. 

329  If  IGNBRK  is  set,  a  break  condition  detected  on  input  is  ignored,  that  is,  not  put 

330  on  the  input  queue  and  therefore  not  read  by  any  process.  If  IGNBRK  is  not  set 

331  and  BRKINT  is  set,  the  break  condition  shall  flush  the  input  and  output  queues. 

332  If  the  terminal  is  the  controlling  terminal  of  a  foreground  process  group,  the 

333  break  condition  shall  generate  a  single  SIGINT  signal  to  that  foreground  process 

334  group.  If  neither  IGNBRK  nor  BRKINT  is  set,  a  break  condition  is  read  as  a  single 

335  'NO',  or  if  PARMRK  is  set,  as  '\377',  '\0',  '\0'. 

336  If  IGNPAR  is  set,  a  byte  with  a  framing  or  parity  error  (other  than  break)  is 

337  ignored. 
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If  PARMRK  is  set  and  IGNPAR  is  not  set,  a  byte  with  a  framing  or  parity  error 
(other  than  break)  is  given  to  the  application  as  the  three-character  sequence 
'\37  7',  '\0',  X,  where  '\37  7',  '\0'  is  a  two-character  flag  preceding  each  sequence 
and  X  is  the  data  of  the  character  received  in  error.  To  avoid  ambiguity  in  this 
case,  if  ISTRIP  is  not  set,  a  valid  character  of  '\ 3 7  7'  is  given  to  the  application  as 
'\37  7',  '\377'.  If  neither  PARMRK  nor  IGNPAR  is  set,  a  framing  or  parity  error 
(other  than  break)  is  given  to  the  application  as  a  single  character  '\  O'. 

If  INPCK  is  set,  input  parity  checking  is  enabled.  If  INPCK  is  not  set,  input  parity 
checking  is  disabled,  allowing  output  parity  generation  without  input  parity 
errors.  Note  that  whether  input  parity  checking  is  enabled  or  disabled  is 
independent  of  whether  parity  detection  is  enabled  or  disabled  (see  7.1.2. 4).  If 
parity  detection  is  enabled,  but  input  parity  checking  is  disabled,  the  hardware  to 
which  the  terminal  is  connected  shall  recognize  the  parity  bit,  but  the  terminal 
special  file  shall  not  check  whether  this  bit  is  set  correctly  or  not. 

If  ISTRIP  is  set,  valid  input  bytes  are  first  stripped  to  seven  bits;  otherwise,  all 
eight  bits  are  processed. 

If  INLCR  is  set,  a  received  NL  character  is  translated  into  a  CR  character.  If 
IGNCR  is  set,  a  received  CR  character  is  ignored  (not  read).  If  IGNCR  is  not  set 
and  ICRNL  is  set,  a  received  CR  character  is  translated  into  a  NL  character. 

If  IXON  is  set,  start/stop  output  control  is  enabled.  A  received  STOP  character 
shall  suspend  output,  and  a  received  START  character  shall  restart  output.  When 
IXON  is  set,  START  and  STOP  characters  are  not  read,  but  merely  perform  flow 
control  functions.  When  IXON  is  not  set,  the  START  and  STOP  characters  are 
read. 

If  IXOFF  is  set,  start/stop  input  control  is  enabled.  The  system  shall  transmit  one 
or  more  STOP  characters,  which  are  intended  to  cause  the  terminal  device  to  stop 
transmitting  data,  as  needed  to  prevent  the  input  queue  from  overflowing  and  | 
causing  the  undefined  behavior  described  in  7. 1.1. 5  and  shall  transmit  one  or  | 
more  START  characters,  which  are  intended  to  cause  the  terminal  device  to 
resume  transmitting  data,  as  soon  as  the  device  can  continue  transmitting  data 
without  risk  of  overflowing  the  input  queue.  The  precise  conditions  under  which 
STOP  and  START  characters  are  transmitted  are  implementation  defined. 

The  initial  input  control  value  after  open  ()  is  implementation  defined. 

7. 1.2.3  Output  Modes 

Values  of  the  c_oflag  field  describe  the  basic  terminal  output  control  and  are  com¬ 
posed  of  the  bitwise  inclusive  OR  of  the  following  masks,  which  shall  be  bitwise 
distinct: 


Mask  Name  _ Description _ 

OPOST  Perform  output  processing. 

The  mask  name  symbols  for  the  cjoflag  field  are  defined  in  <termios  .  h>. 

If  OPOST  is  set,  output  data  is  processed  in  an  implementation-defined  fashion  so 
that  lines  of  text  are  modified  to  appear  appropriately  on  the  terminal  device; 
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380  otherwise,  characters  are  transmitted  without  change. 

381  The  initial  output  control  value  after  open  ()  is  implementation  defined. 

382  7. 1.2.4  Control  Modes 

383  Values  of  the  c_cflag  field,  shown  in  Table  7-3,  describe  the  basic  terminal 

384  hardware  control  and  are  composed  of  the  bitwise  inclusive  OR  of  the  masks 

385  shown,  which  shall  be  bitwise  distinct;  not  all  values  specified  are  required  to  be 

386  supported  by  the  underlying  hardware.  The  mask  name  symbols  in  this  table  are 

387  defined  in  <termios  .  h>. 


388  Table  7-3  -  termios  c_cflag  Field 

389  _ 


390 

Mask  Name 

Description 

391 

CLOCAL 

Ignore  modem  status  lines. 

392 

CREAD 

Enable  receiver. 

393 

CSIZE 

Number  of  bits  per  byte: 

394 

CS5 

5  bits 

395 

CS6 

6  bits 

396 

CS7 

7  bits 

397 

CS8 

8  bits 

398 

CSTOPB 

Send  two  stop  bits,  else  one. 

399 

HUPCL 

Hang  up  on  last  close. 

400 

PARENB 

Parity  enable. 

401 

PARODD 

Odd  parity,  else  even. 

402 

403  The  CSIZE  bits  specify  the  byte  size  in  bits  for  both  transmission  and  reception. 

404  This  size  does  not  include  the  parity  bit,  if  any.  If  CSTOPB  is  set,  two  stop  bits  are 

405  used;  otherwise,  one  stop  bit  is  used.  For  example,  at  110  baud,  two  stop  bits  are 

406  normally  used. 

407  If  CREAD  is  set,  the  receiver  is  enabled;  otherwise,  no  characters  shall  be 

408  received. 

409  If  PARENB  is  set,  parity  generation  and  detection  is  enabled  and  a  parity  bit  is 

410  added  to  each  character.  If  parity  is  enabled,  PARODD  specifies  odd  parity  if  set; 

411  otherwise,  even  parity  is  used. 

412  If  HUPCL  is  set,  the  modem  control  lines  for  the  port  shall  be  lowered  when  the 

413  last  process  with  the  port  open  closes  the  port  or  the  process  terminates.  The 

414  modem  connection  shall  be  broken. 

415  If  CLOCAL  is  set,  a  connection  does  not  depend  on  the  state  of  the  modem  status 

416  lines.  If  CLOCAL  is  clear,  the  modem  status  lines  shall  be  monitored. 

417  Under  normal  circumstances,  a  call  to  the  open()  function  shall  wait  for  the 

418  modem  connection  to  complete.  However,  if  the  0_NONBLOCK  flag  is  set  (see 

419  5.3.1)  or  if  CLOCAL  has  been  set,  the  open ()  function  shall  return  immediately 

420  without  waiting  for  the  connection. 

421  If  the  object  for  which  the  control  modes  are  set  is  not  an  asynchronous  serial  con- 

422  nection,  some  of  the  modes  may  be  ignored;  for  example,  if  an  attempt  is  made  to 
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423  set  the  baud  rate  on  a  network  connection  to  a  terminal  on  another  host,  the  baud 

424  rate  may  or  may  not  be  set  on  the  connection  between  that  terminal  and  the 

425  machine  to  which  it  is  directly  connected. 

426  The  initial  hardware  control  value  after  open()  is  implementation  defined. 

427  7. 1.2.5  Local  Modes 

428  Values  of  the  c_lflag  field,  shown  in  Table  7-4,  describe  the  control  of  various  func- 

429  tions  and  are  composed  of  the  bitwise  inclusive  OR  of  the  masks  shown,  which 

430  shall  be  bitwise  distinct.  The  mask  name  symbols  in  this  table  are  defined  in 

431  <termios.h>. 

432  Table  7-4  -  termios  cjiflag  Field  | 

433  _ _ _ _ 


434 

Mask  Name 

Description 

435 

ECHO 

Enable  echo. 

436 

ECHOE 

Echo  ERASE  as  an  error-correcting  backspace. 

437 

ECHOK 

Echo  KILL. 

438 

ECHONL 

Echo  '\n\ 

439 

ICANON 

Canonical  input  (erase  and  kill  processing). 

440 

IEXTEN 

Enable  extended  (implementation-defined)  functions. 

441 

ISIG 

Enable  signals. 

442 

NOFLSH 

Disable  flush  after  interrupt,  quit,  or  suspend. 

443 

TOSTOP 

Send  SIGTTOU  for  background  output. 

444 

445  If  ECHO  is  set,  input  characters  are  echoed  back  to  the  terminal.  If  ECHO  is  not 

446  set,  input  characters  are  not  echoed. 

447  If  ECHOE  and  ICANON  are  set,  the  ERASE  character  shall  cause  the  terminal  to 

448  erase  the  last  character  in  the  current  line  from  the  display,  if  possible.  If  there  is 

449  no  character  to  erase,  an  implementation  may  echo  an  indication  that  this  was 

450  the  case  or  do  nothing. 

451  If  ECHOK  and  ICANON  are  set,  the  KILL  character  shall  either  cause  the  terminal 

452  to  erase  the  line  from  the  display  or  shall  echo  the  '\n'  character  after  the  KILL 

453  character. 

454  If  ECHONL  and  ICANON  are  set,  the  '\n'  character  shall  be  echoed  even  if  ECHO 

455  is  not  set. 

456  If  ICANON  is  set,  canonical  processing  is  enabled.  This  enables  the  erase  and  kill 

457  edit  functions  and  the  assembly  of  input  characters  into  lines  delimited  by  NL, 

458  EOF,  and  EOL,  as  described  in  7.1. 1.6. 

459  If  ICANON  is  not  set,  read  requests  are  satisfied  directly  from  the  input  queue.  A 

460  read  shall  not  be  satisfied  until  at  least  MIN  bytes  have  been  received  or  the 

461  timeout  value  TIME  has  expired  between  bytes.  The  time  value  represents  tenths 

462  of  seconds.  See  7. 1.1.7  for  more  details. 

463  If  ISIG  is  set,  each  input  character  is  checked  against  the  special  control  charac- 

464  ters  INTR,  QUIT,  and  SUSP  (job  control  only).  If  an  input  character  matches  one  of 

465  these  control  characters,  the  function  associated  with  that  character  is  performed. 
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466  If  ISIG  is  not  set,  no  checking  is  done.  Thus,  these  special  input  functions  are  pos- 

467  sible  only  if  ISIG  is  set. 

468  If  IEXTEN  is  set,  implementation- defined  functions  shall  be  recognized  from  the 

469  input  data.  It  is  implementation  defined  how  IEXTEN  being  set  interacts  with 

470  ICANON,  ISIG,  IXON,  or  IXOFF.  If  IEXTEN  is  not  set,  then  implementation-defined 

471  functions  shall  not  be  recognized,  and  the  corresponding  input  characters  shall  be 

472  processed  as  described  for  ICANON,  ISIG,  IXON,  and  IXOFF. 

473  If  NOFLSH  is  set,  the  normal  flush  of  the  input  and  output  queues  associated  with 

474  the  INTR,  QUIT,  and  SUSP  (job  control  only)  characters  shall  not  be  done. 

475  If  TOSTOP  is  set  and  the  implementation  supports  job  control,  the  signal  SIGTTOU 

476  is  sent  to  the  process  group  of  a  process  that  tries  to  write  to  its  controlling  termi- 

477  nal  if  it  is  not  in  the  foreground  process  group  for  that  terminal.  This  signal,  by 

478  default,  stops  the  members  of  the  process  group.  Otherwise,  the  output  generated 

479  by  that  process  is  output  to  the  current  output  stream.  Processes  that  are  block- 

480  ing  or  ignoring  SIGTTOU  signals  are  excepted  and  allowed  to  produce  output,  and 

481  the  SIGTTOU  signal  is  not  sent. 

482  The  initial  local  control  value  after  open  ()  is  implementation  defined. 

483  7. 1.2.6  Special  Control  Characters 

484  The  special  control  characters  values  are  defined  by  the  array  c_cc.  The  subscript 

485  name  and  description  for  each  element  in  both  canonical  and  noncanonical  modes 

486  are  shown  in  Table  7-5.  The  subscript  name  symbols  in  this  table  are  defined  in 

487  <termios.h>. 

488  Table  7-5  -  termios  c_cc  Special  Control  Characters  | 

489  _ 


490 

Subscript  Usage 

491 

Canonical 

Noncanonical 

Description 

492 

Mode 

Mode 

493 

VEOF 

EOF  character 

494 

VEOL 

EOL  character 

495 

VERASE 

ERASE  character 

496 

VINTR 

VINTR 

INTR  character 

497 

VK3LL 

KILL  character 

498 

VMIN 

MIN  value 

499 

VQUIT 

VQUIT 

QUIT  character 

500 

VSUSP 

VSUSP 

SUSP  character 

501 

VTIME 

TIME  value 

502 

VST ART 

VST ART 

START  character 

503 

504 

VSTOP 

VSTOP 

STOP  character 

505  The  subscript  values  shall  be  unique,  except  that  the  VMIN  and  VTIME  subscripts 

506  may  have  the  same  values  as  the  VEOF  and  VEOL  subscripts,  respectively. 

507  Implementations  that  do  not  support  job  control  may  ignore  the  SUSP  character 

508  value  in  the  c_cc  array  indexed  by  the  VSUSP  subscript. 
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509  The  value  of  NCCS  (the  number  of  elements  in  the  c_cc  array)  is  unspecified  by  | 

510  this  part  of  ISO/IEC  9945.  | 

511  Implementations  that  do  not  support  changing  the  START  and  STOP  characters 

512  may  ignore  the  character  values  in  the  c_cc  array  indexed  by  the  VSTART  and 

513  VSTOP  subscripts  when  tcsetattr()  is  called,  but  shall  return  the  value  in  use 

514  when  tcgetattr{ )  is  called. 

515  If  LPOSIX_VDISABLE}  is  defined  for  the  terminal  device  file,  and  the  value  of  one 

516  of  the  changeable  special  control  characters  (see  7. 1.1.9)  is  {_POSIX_VDISABLE}, 

517  that  function  shall  be  disabled,  that  is,  no  input  data  shall  be  recognized  as  the 

518  disabled  special  character.  If  ICANON  is  not  set,  the  value  of  {_POSIX_VDISABLE} 

519  has  no  special  meaning  for  the  VMIN  and  VTIME  entries  of  the  cjcc  array. 

520  The  initial  values  of  all  control  characters  are  implementation  defined. 

521  7.1.2.7  Baud  Rate  Values  | 

522  The  baud  rate  values  specified  in  Table  7-6  can  be  set  into  the  termios  structure  | 

523  by  the  baud  rate  functions  in  7.1.3. 


524  Table  7-6  -  termios  Baud  Rate  Values 

525  _ 


526 

Name 

Description 

Name 

Description 

527 

B0 

Hang  up 

B600 

600  baud 

528 

B50 

50  baud 

B1200 

1200  baud 

529 

B75 

75  baud 

B1800 

1800  baud 

530 

B110 

110  baud 

B2400 

2400  baud 

531 

B134 

134.5  baud 

B4800 

4800  baud 

532 

B150 

150  baud 

B9600 

9600  baud 

533 

B200 

200  baud 

B19200 

19  200  baud 

534 

B300 

300  baud 

B38400 

38  400  baud 

535 


536  7.1 .3  Baud  Rate  Functions 

537  Functions:  cfgetispeedO,  cfgetospeedO,  cfsetispeedO,  cfsetospeedO 


538 

539 

540 

541 

542 

543 


7. 1.3.1  Synopsis 


♦include  <termios.h> 

speed_t  cfgetospeed (const  struct  termios 
int  cfsetospeed  (struct  termios  *termios_p, 
speed_t  cfgetispeed (const  struct  termios 
int  cfsetispeed  (struct  termios  *termios_p, 


Hermios j o)  ; 
speed_t  speed)  ; 
Hermios _p)  ; 
speed_t  speed)  ; 
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544  7.1.3.2  Description 

545  The  following  interfaces  are  provided  for  getting  and  setting  the  values  of  the  | 

546  input  and  output  baud  rates  in  the  termios  structure.  The  effects  on  the  terminal  | 

547  device  described  below  do  not  become  effective  until  the  tcsetattri )  function  is  sue-  | 

548  cessfully  called,  and  not  all  errors  are  detected  until  tcsetattri )  is  called  as  well. 

549  The  input  and  output  baud  rates  are  represented  in  the  termios  structure.  The  | 

550  values  shown  in  Table  7-6  are  defined.  The  name  symbols  in  this  table  are  | 

551  defined  in  <termios  .  h>. 

552  The  type  speedj  shall  be  defined  in  <termios.h>  and  shall  be  an  unsigned  | 

553  integral  type.  | 

554  The  termios _p  argument  is  a  pointer  to  a  termios  structure. 

555  The  cfgetospeedi)  function  shall  return  the  output  baud  rate  stored  in  the  termios  \ 

556  structure  to  which  termios _p  points.  | 

557  The  cfgetispeedO  function  shall  return  the  input  baud  rate  stored  in  the  termios 

558  structure  to  which  termios _p  points.  | 

559  The  cfsetospeedi)  function  shall  set  the  output  baud  rate  stored  in  the  termios  \ 

560  structure  to  which  termios _p  points. 

561  The  cfsetispeedO  function  shall  set  the  input  baud  rate  stored  in  the  termios  | 

562  structure  to  which  termios _p  points.  | 

563  Certain  values  for  speeds  that  are  set  in  the  termios  structure  and  passed  to  | 

564  tcsetattri )  have  special  meanings.  These  are  discussed  under  tcsetattri ).  | 

565  The  cfgetispeedi )  and  cfgetospeedi )  functions  return  exactly  the  value  found  in  the  | 

566  termios  data  structure,  without  interpretation. 

567  Both  cfsetispeedO  and  cfsetospeedi )  return  a  value  of  zero  if  successful  and  -1  to  | 

568  indicate  an  error.  It  is  unspecified  whether  these  return  an  error  if  an  unsup-  | 

569  ported  baud  rate  is  set.  | 

570  7. 1.3.3  Returns 

571  See  7.1. 3. 2. 

572  7. 1.3.4  Errors 

573  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

574  to  be  detected  for  the  cfgetispeedO,  cfgetospeedi),  cfsetispeedO,  or  cfsetospeedi) 

575  functions.  Some  errors  may  be  detected  under  conditions  that  are  unspecified  by  | 

576  this  part  of  ISO/IEC  9945.  j 

577  7. 1.3.5  Cross-References 

578  tesetattri ),  7.2.1. 
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579  7.2  General  Terminal  Interface  Control  Functions 

580  The  functions  that  are  used  to  control  the  general  terminal  function  are  described 

581  in  this  clause.  If  the  implementation  supports  job  control,  unless  otherwise  noted  | 

582  for  a  specific  command,  these  functions  are  restricted  from  use  by  background 

583  processes.  Attempts  to  perform  these  operations  shall  cause  the  process  group  to 

584  be  sent  a  SIGTTOU  signal.  If  the  calling  process  is  blocking  or  ignoring  SIGTTOU 

585  signals,  the  process  is  allowed  to  perform  the  operation  and  the  SIGTTOU  signal  is 

586  not  sent. 

587  In  all  the  functions,  fildes  is  an  open  file  descriptor.  However,  the  functions  affect 

588  the  underlying  terminal  file,  not  just  the  open  file  description  associated  with  the 

589  file  descriptor. 

590  7.2.1  Get  and  Set  State 

59 1  Functions :  tcgetattr  { ),  tcsetattr ( ) 

592  7.2.1. 1  Synopsis 

593  #include  <termios.h> 

594  int  tcgetattr  (int  fildes,  struct  termios  *termios _p)  ; 

595  int  tcsetattr  (int  fildes,  int  optional jactions , 

596  const  struct  termios  *  termios _p)  ; 

597  7.2.1.2  Description 

598  The  tcgetattr()  function  shall  get  the  parameters  associated  with  the  object 

599  referred  to  by  fildes  and  store  them  in  the  termios  structure  referenced  by 

600  termios _p.  This  function  is  allowed  from  a  background  process;  however,  the  ter- 

601  minal  attributes  may  be  subsequently  changed  by  a  foreground  process.  If  the  | 

602  terminal  device  supports  different  input  and  output  baud  rates,  the  baud  rates  | 

603  stored  in  the  termios  structure  returned  by  tcgetattr ( )  shall  reflect  the  actual  baud  | 

604  rates,  even  if  they  are  equal.  If  differing  baud  rates  are  not  supported,  the  rate  | 

605  returned  as  the  output  baud  rate  shall  be  the  actual  baud  rate.  The  rate  returned  | 

606  as  the  input  baud  rate  shall  be  either  the  number  zero  or  the  output  rate  (as  one  | 

607  of  the  symbolic  values).  Permitting  either  behavior  is  obsolescent.4)  | 

608  The  tcsetattr ()  function  shall  set  the  parameters  associated  with  the  terminal 

609  (unless  support  is  required  from  the  underlying  hardware  that  is  not  available) 

610  from  the  termios  structure  referenced  by  termios _p  as  follows: 

611  (1)  If  optional  jactions  is  TCSANOW,  the  change  shall  occur  immediately. 


612  4)  In  a  future  revision  of  this  part  of  ISO/EEC  9945,  a  returned  value  of  zero  as  the  input  baud  rate 

613  when  differing  baud  rates  are  not  supported  may  no  longer  be  permitted. 
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(2)  If  optional _actions  is  TCSADRAIN,  the  change  shall  occur  after  all  output 
written  to  fildes  has  been  transmitted.  This  function  should  be  used 
when  changing  parameters  that  affect  output. 

(3)  If  optional  jactions  is  TCSAFLUSH,  the  change  shall  occur  after  all  output 
written  to  the  object  referred  to  by  fildes  has  been  transmitted,  and  all 
input  that  has  been  received,  but  not  read,  shall  be  discarded  before  the 
change  is  made. 

The  symbolic  constants  for  the  values  of  optional  jactions  are  defined  in 
<termios . h>. 

The  zero  baud  rate,  BO,  is  used  to  terminate  the  connection.  If  BO  is  specified  as 
the  output  baud  rate  when  tcsetattr ()  is  called,  the  modem  control  lines  shall  no 
longer  be  asserted.  Normally,  this  will  disconnect  the  line. 

If  the  input  baud  rate  is  equal  to  the  numeral  zero  in  the  termios  structure  when 
tcsetattri )  is  called,  the  input  baud  rate  will  be  changed  by  tcsetattri )  to  the  same 
value  as  that  specified  by  the  value  of  the  output  baud  rate,  exactly  as  if  the  input 
rate  had  been  set  to  the  output  rate  by  cfsetispeedi).  This  usage  of  zero  is 
obsolescent. 

The  tcsetattri )  function  shall  return  success  if  it  was  able  to  perform  any  of  the 
requested  actions,  even  if  some  of  the  requested  actions  could  not  be  performed. 
It  shall  set  all  the  attributes  that  the  implementation  does  support  as  requested 
and  leave  all  the  attributes  not  supported  by  the  hardware  unchanged.  If  no  part 
of  the  request  can  be  honored,  it  shall  return  -1  and  set  errno  to  [EINVAL].  If  the 
input  and  output  baud  rates  differ  and  are  a  combination  that  is  not  supported, 
neither  baud  rate  is  changed.  A  subsequent  call  to  tcgetattri)  shall  return  the 
actual  state  of  the  terminal  device  [reflecting  both  the  changes  made  and  not 
made  in  the  previous  tcsetattri )  calll.  The  tcsetattri )  function  shall  not  change  the 
values  in  the  termios  structure  whether  or  not  it  actually  accepts  them. 

The  termios  structure  may  have  additional  fields  not  defined  by  this  part  of 
ISO/IEC  9945.  The  effect  of  the  tcsetattri)  function  is  undefined  if  the  value  of  the 
termios  structure  pointed  to  by  termios _p  was  not  derived  from  the  result  of  a  call 
to  tcgetattri)  on  fildes’,  a  Strictly  Conforming  POSIX.1  Application  shall  modify 
only  fields  and  flags  defined  by  this  part  of  ISO/IEC  9945  between  the  call  to 
tcgetattri)  and  tcsetattri),  leaving  all  other  fields  and  flags  unmodified. 

No  actions  defined  by  this  part  of  ISO/IEC  9945,  other  than  a  call  to  tcsetattri)  or  a 
close  of  the  last  file  descriptor  in  the  system  associated  with  this  terminal  device, 
shall  cause  any  of  the  terminal  attributes  defined  by  this  part  of  ISO/IEC  9945  to 
change. 

7.2.1.3  Returns 

Upon  successful  completion,  a  value  of  zero  is  returned.  Otherwise,  a  value  of-1 
is  returned  and  errno  is  set  to  indicate  the  error. 
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654  7.2.1.4  Errors 


655  If  any  of  the  following  conditions  occur,  the  tcgetattri)  function  shall  return  -1 

656  and  set  errno  to  the  corresponding  value: 


657  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

658  [ENOTTYl  The  file  associated  with  fildes  is  not  a  terminal. 


659  If  any  of  the  following  conditions  occur,  the  tcsetattri )  function  shall  return  -1  and 

660  set  errno  to  the  corresponding  value: 


661 

662 

663 

664 

665 


[EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

[EINTR]  A  signal  interrupted  the  tcsetattri )  function. 

[EINVAL]  The  optional jactions  argument  is  not  a  proper  value,  or  an 
attempt  was  made  to  change  an  attribute  represented  in  the 
termios  structure  to  an  unsupported  value. 


666  [ENOTTY]  The  file  associated  with  fildes  is  not  a  terminal. 


667  7.2.1.5  Cross-References 

668  <termios  .  h>,  7.1.2. 


669  7.2.2  Line  Control  Functions 

670  Functions:  tcsendbreaki),  tcdraini),  tcflushi),  tcflowi) 


677  7.2.2.2  Description 

678  If  the  terminal  is  using  asynchronous  serial  data  transmission,  the  tcsendbreaki ) 

679  function  shall  cause  transmission  of  a  continuous  stream  of  zero-valued  bits  for  a 

680  specific  duration.  If  duration  is  zero,  it  shall  cause  transmission  of  zero-valued 

681  bits  for  at  least  0,25  seconds  and  not  more  that  0,5  seconds.  If  duration  is  not 

682  zero,  it  shall  send  zero-valued  bits  for  an  implementation- defined  period  of  time. 

683  If  the  terminal  is  not  using  asynchronous  serial  data  transmission,  it  is  imple- 

684  mentation  defined  whether  the  tcsendbreaki)  function  sends  data  to  generate  a 

685  break  condition  (as  defined  by  the  implementation)  or  returns  without  taking  any 

686  action. 

687  The  tcdraini)  function  shall  wait  until  all  output  written  to  the  object  referred  to 

688  by  fildes  has  been  transmitted. 


671 

7.2.2.1  Synopsis 

672 

♦include  <termios.h> 

673 

int  tcsendbreak  ( int  fildes, 

int  duration)  ; 

674 

int  tcdrain(int  fildes); 

675 

int  tcf  lush  (int  fildes,  int 

queue  ^selector)  ; 

676 

int  tcflow(int  fildes,  int 

action)  ; 

7.2  General  Terminal  Interface  Control  Functions 
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Upon  successful  completion,  the  tcflushi)  function  shall  have  discarded  any  data  | 
written  to  the  object  referred  to  by  fildes  but  not  transmitted,  or  data  received,  but  | 
not  read,  depending  on  the  value  of  queue _selector: 

(1)  If  queue  jselector  is  TCIFLUSH,  it  shall  flush  data  received,  but  not  read. 

(2)  If  queue  jselector  is  TCOFLUSH,  it  shall  flush  data  written,  but  not 
transmitted. 

(3)  If  queue  _selector  is  TCIOFLUSH,  it  shall  flush  both  data  received  but  not 
read  and  data  written  but  not  transmitted. 

The  tcflowi)  function  shall  suspend  transmission  or  reception  of  data  on  the  object 
referred  to  by  fildes ,  depending  on  the  value  of  action : 

(1)  If  action  is  TCOOFF,  it  shall  suspend  output. 

(2)  If  action  is  TCOON,  it  shall  restart  suspended  output. 

(3)  If  action  is  TCIOFF,  the  system  shall  transmit  a  STOP  character,  which  is 
intended  to  cause  the  terminal  device  to  stop  transmitting  data  to  the 
system.  (See  the  description  of  IXOFF  in  7. 1.2.2.) 

(4)  If  action  is  TCION,  the  system  shall  transmit  a  START  character,  which  is 
intended  to  cause  the  terminal  device  to  start  transmitting  data  to  the 
system.  (See  the  description  of  IXOFF  in  7. 1.2.2.) 

The  symbolic  constants  for  the  values  of  queue  jselector  and  action  are  defined  in 
ctermios . h>. 

The  default  on  the  opening  of  a  terminal  file  is  that  neither  its  input  nor  its  out¬ 
put  is  suspended. 

7.2.2.3  Returns 

Upon  successful  completion,  a  value  of  zero  is  returned.  Otherwise,  a  value  of  -1 
is  returned  and  errno  is  set  to  indicate  the  error. 


714  T.2.2.4  Errors 

715  If  any  of  the  following  conditions  occur,  the  tcsendbreaki)  function  shall  return  -1 

716  and  set  errno  to  the  corresponding  value: 

717  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

718  [ENOTTY]  The  file  associated  with  fildes  is  not  a  terminal. 

719  If  any  of  the  following  conditions  occur,  the  tcdrain  ()  function  shall  return  -1  and 

720  set  errno  to  the  corresponding  value: 

721  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

722  [EINTR]  A  signal  interrupted  the  tcdrain  ()  function. 

723  [ENOTTY]  The  file  associated  with  fildes  is  not  a  terminal. 

724  If  any  of  the  following  conditions  occur,  the  tcflushi)  function  shall  return  -1  and 

725  set  errno  to  the  corresponding  value: 
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726  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

727  [EINVAL]  The  queue jselector  argument  is  not  a  proper  value. 

728  [ENOTTY]  The  file  associated  with  fildes  is  not  a  terminal. 

729  If  any  of  the  following  conditions  occur,  the  tcflowO  function  shall  return  -1  and 

730  set  errno  to  the  corresponding  value: 

731  [EBADF1  The  fildes  argument  is  not  a  valid  file  descriptor. 

732  [EINVAL]  The  action  argument  is  not  a  proper  value. 

733  [ENOTTY]  The  file  associated  with  fildes  is  not  a  terminal. 

734  7.2. 2.5  Cross-References 

735  <termios  .  h>,  7.1.2. 


736  7.2.3  Get  Foreground  Process  Group  ID 

737  Function:  tcgetpgrp  () 

738  7.2.3.1  Synopsis 

739  #include  <sys/types  . h> 

740  pid_t  tcgetpgrp  (int  fildes); 


741  7.2.3.2  Description 


742  If  {_POSIX_JOB_CONTROL}  is  defined: 


743  (1)  The  tcgetpgrp  ()  function  shall  return  the  value  of  the  process  group  ID  of 

744  the  foreground  process  group  associated  with  the  terminal. 


745 

746 

747 

748 


(2)  The  tcgetpgrp  ()  function  is  allowed  from  a  process  that  is  a  member  of  a 
background  process  group;  however,  the  information  may  be  subse¬ 
quently  changed  by  a  process  that  is  a  member  of  a  foreground  process 
group. 


749  Otherwise: 


750  The  implementation  shall  either  support  the  tcgetpgrp  ()  function  as 

751  described  above  or  the  tcgetpgrp  ( )  call  shall  fail. 


752  7.2.3.3  Returns 

753  Upon  successful  completion,  tcgetpgrp  ()  returns  the  process  group  ID  of  the  fore- 

754  ground  process  group  associated  with  the  terminal.  If  there  is  no  foreground  pro-  | 

755  cess  group,  tcgetpgrp  ()  shall  return  a  value  greater  than  1  that  does  not  match  | 

756  the  process  group  ID  of  any  existing  process  group.  Otherwise,  a  value  of  -1  is  | 

757  returned  and  errno  is  set  to  indicate  the  error. 


7.2  General  Terminal  Interface  Control  Functions 


147 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


INFORMATION  TECHNOLOGY— POSIX 


758  7.2.3.4  Errors 


759  If  any  of  the  following  conditions  occur,  the  tcgetpgrp  ()  function  shall  return  -1 

760  and  set  errno  to  the  corresponding  value: 

761  [EBADF]  The  fildes  argument  is  not  a  valid  file  descriptor. 

762  [ENOSYS]  The  tcgetpgrp  ()  function  is  not  supported  in  this  implementa- 

763  tion. 


764  [ENOTTY]  The  calling  process  does  not  have  a  controlling  terminal,  or  the 

765  file  is  not  the  controlling  terminal. 


766  7.2.3.5  Cross-References 

767  setsidO,  4.3.2;  setpgidi ),  4.3.3;  tcsetpgrp (),  7.2.4. 


768  7.2.4  Set  Foreground  Process  Group  ED 

769  Function:  tcsetpgrp  ( ) 

770  7.2.4. 1  Synopsis 

771  #include  <sys/types . h> 

772  int  tcsetpgrp  ( int  fildes,  pid_t  pgrp_id)  ; 

773  7.2.4.2  Description 

774  If  LPOSIX_JOB_CONTROL}  is  defined: 

775  If  the  process  has  a  controlling  terminal,  the  tcsetpgrp ()  function  shall  set 

776  the  foreground  process  group  ID  associated  with  the  terminal  to  pgrp_id. 

in  The  file  associated  with  fildes  must  be  the  controlling  terminal  of  the  cal- 

778  ling  process,  and  the  controlling  terminal  must  be  currently  associated  with 

779  the  session  of  the  calling  process.  The  value  of  pgrp_id  must  match  a  pro- 

780  cess  group  ID  of  a  process  in  the  same  session  as  the  calling  process. 

781  Otherwise: 

782  The  implementation  shall  either  support  the  tcsetpgrp  ()  function  as 

783  described  above,  or  the  tcsetpgrp  ()  call  shall  fail. 

784  7.2. 4.3  Returns 

785  Upon  successful  completion,  tcsetpgrp  ()  returns  a  value  of  zero.  Otherwise,  a 

786  value  of  -1  is  returned  and  errno  is  set  to  indicate  the  error. 

787  7.2.4.4  Errors 

788  If  any  of  the  following  conditions  occur,  the  tcsetpgrp  ()  function  shall  return  -1 

789  and  set  errno  to  the  corresponding  value: 
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790 

[EBADF] 

The  fildes  argument  is  not  a  valid  file  descriptor. 

791 

792 

[EINVAL] 

The  value  of  the  pgrp_id  argument  is  not  supported  by  the 
implementation. 

793 

794 

[ENOSYS] 

The  tcsetpgrp  ()  function  is  not  supported  in  this 
implementation. 

795 

796 

797 

[ENOTTY] 

The  calling  process  does  not  have  a  controlling  terminal,  or  the 
file  is  not  the  controlling  terminal,  or  the  controlling  terminal  is 
no  longer  associated  with  the  session  of  the  calling  process. 

798 

799 

800 

[EPERM] 

The  value  of  pgrp_id  is  a  value  supported  by  the  implementa¬ 
tion,  but  does  not  match  the  process  group  ID  of  a  process  in  the 
same  session  as  the  calling  process. 
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Section  8:  Language-Specific  Services  for  the  C  Programming 
Language 


8.1  Referenced  C  Language  Routines 

The  functions  listed  below  are  described  in  the  indicated  sections  of  the 
C  Standard  {2}.  POSIX.l  with  the  C  Language  Binding  comprises  these  functions,  | 
the  extensions  to  them  described  in  this  clause,  and  the  rest  of  the  requirements  | 
stipulated  in  this  part  of  ISO/IEC  9945.  The  functions  appended  with  plus  signs 
(+)  have  requirements  beyond  those  set  forth  in  the  C  Standard  {2}.  Any  imple¬ 
mentation  claiming  conformance  to  POSIX.1  with  the  C  Language  Binding  shall  | 
comply  with  the  requirements  outlined  in  this  clause,  the  requirements  stipulated  | 
in  the  rest  of  this  part  of  ISO/IEC  9945,  and  the  requirements  in  the  indicated  sec-  | 
tions  of  the  C  Standard  {2}.  | 

For  requirements  concerning  conformance  to  this  clause,  see  1.3.3  and  its  | 
subclauses. 

4.2  Diagnostics 
Functions:  assert. 

4.3  Character  Handling 

Functions:  isalnum,  isalpha,  iscntrl,  isdigit,  isgraph,  islower,  isprint, 
ispunct,  isspace,  isupper,  isxdigit,  tolower,  toupper. 

4.4  Localization 
Functions:  setlocale+. 

4.5  Mathematics 

Functions:  acos,  asin,  atan,  atan2,  cos,  sin,  tan,  cosh,  sinh,  tanh,  exp, 
frexp,  ldexp,  log,  loglO,  modf,  pow,  sqrt,  ceil,  fabs,  floor,  fmod. 

4.6  Non-Local  Jumps 
Functions:  setjmp,  longjmp. 

4.9  Input/Output 

Functions:  clearerr,  fclose,  feof,  ferror,  fflush,  fgetc,  fgets,  fopen,  fputc, 
fputs,  fread,  freopen,  fseek,  ftell,  fwrite,  getc,  getchar,  gets,  perror, 
printf,  fprintf,  sprintf,  putc,  putchar,  puts,  remove,  rename+,  rewind, 
scanf,  fscanf,  sscanf,  setbuf,  tmpfile,  tmpnam,  ungetc. 

4.10  General  Utilities 

Functions:  abs,  atof,  atoi,  atol,  rand,  srand,  calloc,  free,  malloc,  realloc, 
abort+,  exit,  getenv+,  bsearch,  qsort. 

4.11  String  Handling 

Functions:  strcpy,  stmcpy,  strcat,  stmcat,  strcmp,  stmcmp,  strchr, 
strcspn,  strpbrk,  strrchr,  strspn,  strstr,  strtok,  strlen. 


8.1  Referenced  C  Language  Routines 
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36  4.12  Date  and  Time 

37  Functions:  time,  asctime,  ctime+,  gmtime+,  localtime+,  mktime+, 

38  strftime+. 

39  Systems  conforming  to  this  part  of  ISO/IEC  9945  shall  make  no  distinction 

40  between  the  “text  streams”  and  the  “binary  streams”  described  in  the 

41  C  Standard  {2}. 

42  For  the  fseek  ()  function,  if  the  specified  position  is  beyond  end-of-file,  the  conse- 

43  quences  described  in  Iseek ()  (see  6.5.3)  shall  occur. 

44  The  EXIT_SUCCESS  macro,  as  used  by  the  exit()  function,  shall  evaluate  to  a 

45  value  of  zero.  Similarly,  the  EXIT_FAILURE  macro  shall  evaluate  to  a  nonzero  | 

46  value.  | 

47  The  relationship  between  a  time  in  seconds  since  the  Epoch  used  as  an  argument 

48  to  gmtimei )  and  the  tm  structure  (defined  in  <t  ime .  h>)  is  that  the  result  shall  be 

49  as  specified  in  the  expression  given  in  the  definition  of  seconds  since  the  Epoch  in 

so  2.2.2.77,  where  the  names  in  the  structure  and  in  the  expression  correspond.  If 

51  the  time  zone  uctO  is  in  effect,  this  shall  also  be  true  for  localtime+)  and 

52  mktimei). 

53  8.1.1  Extensions  to  Time  Functions 

54  The  contents  of  the  environment  variable  named  TZ  (see  2.6)  shall  be  used  by  the 

55  functions  ctime(),  localtime {),  strftimeO,  and  mktimei)  to  override  the  default 

56  time  zone.  The  value  of  TZ  has  one  of  the  two  forms  (spaces  inserted  for  clarity): 

57  :  characters 

58 

59 

60 
61 

62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 
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or: 

std  offset  dst  offset ,  rule 

If  TZ  is  of  the  first  format  (i.e.,  if  the  first  character  is  a  colon),  the  characters  fol¬ 
lowing  the  colon  are  handled  in  an  implementation-defined  manner. 

The  expanded  format  (for  all  TZs  whose  value  does  not  have  a  colon  as  the  first 
character)  is  as  follows: 

stdoffset[dst[offset][ ,  start[  /  time] ,  end[  /time]]] 

Where: 

std  and  dst  Indicates  no  less  than  three,  nor  more  than  {TZNAME_MAX},  | 
bytes  that  are  the  designation  for  the  standard  ( std )  or  summer  | 
(dst)  time  zone.  Only  std  is  required;  if  dst  is  missing,  then  sum¬ 
mer  time  does  not  apply  in  this  locale.  Upper-  and  lowercase 
letters  are  explicitly  allowed.  Any  characters  except  a  leading 
colon  ( : )  or  digits,  the  comma  (, ),  the  minus  (-),  the  plus  (+),  and  | 
the  null  character  are  permitted  to  appear  in  these  fields,  but  | 
their  meaning  is  unspecified. 
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Indicates  the  value  one  must  add  to  the  local  time  to  arrive  at 
Coordinated  Universal  Time.  The  offset  has  the  form: 

hh[ :  mm[ :  ss]] 

The  minutes  (mm )  and  seconds  (ss )  are  optional.  The  hour  (hh ) 
shall  be  required  and  may  be  a  single  digit.  The  offset  following 
std  shall  be  required.  If  no  offset  follows  dst,  summer  time  is 
assumed  to  be  one  hour  ahead  of  standard  time.  One  or  more 
digits  may  be  used;  the  value  is  always  interpreted  as  a  decimal 
number.  The  hour  shall  be  between  zero  and  24,  and  the 
minutes  (and  seconds) — if  present — between  zero  and  59.  Use  of 
values  outside  these  ranges  causes  undefined  behavior.  If  pre¬ 
ceded  by  a  the  time  zone  shall  be  east  of  the  Prime  Meri¬ 
dian;  otherwise  it  shall  be  west  (which  may  be  indicated  by  an 
optional  preceding 

Indicates  when  to  change  to  and  back  from  summer  time.  The 
rule  has  the  form: 

date  /  time ,  date  /  time 

where  the  first  date  describes  when  the  change  from  standard  to 
summer  time  occurs  and  the  second  date  describes  when  the 
change  back  happens.  Each  time  field  describes  when,  in 
current  local  time,  the  change  to  the  other  time  is  made. 

The  format  of  date  shall  be  one  of  the  following: 

J n  The  Julian  day  n  (1  <  n  <  365).  Leap  days  shall  not  be 

counted.  That  is,  in  all  years — including  leap  years — 
February  28  is  day  59  and  March  1  is  day  60.  It  is 
impossible  to  explicitly  refer  to  the  occasional 
February  29. 

n  The  zero-based  Julian  day  (0  <  n  <  365).  Leap  days 
shall  be  counted,  and  it  is  possible  to  refer  to 
February  29. 

Mm  .  n  .  d 

The  cr  day  (0  <  d  <  6)  of  week  n  of  month  m  of  the 
year  (1  <  rc  <  5,  1  <  m  <  12,  where  week  5  means  “the 
last  d  day  in  month  m”  which  may  occur  in  either  the 
fourth  or  the  fifth  week).  Week  1  is  the  first  week  in 
which  the  cTth  day  occurs.  Day  zero  is  Sunday. 

The  time  has  the  same  format  as  offset  except  that  no  leading 
sign  (“-”  or  “+”)  shall  be  allowed.  The  default,  if  time  is  not 
given,  shall  be  02:00:  00. 

Whenever  dime (),  strftime  (),  mktime (),  or  localtime ()  is  called,  the  time  zone 
names  contained  in  the  external  variable  tzname  shall  be  set  as  if  the  tzset()  func¬ 
tion  had  been  called. 

Applications  are  explicitly  allowed  to  change  TZ  and  have  the  changed  TZ  apply 
to  themselves. 


offset 


rule 
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8.1.2  Extensions  to  setlocalei)  Function 

Function:  setlocale () 

8.1. 2.1  Synopsis 

♦include  <locale.h> 

char  *setlocale  (int  category,  const  char  *  locale )  ; 

8. 1.2.2  Description 

The  setlocale ()  function  sets,  changes,  or  queries  the  locale  of  the  process  accord-  | 
ing  to  the  values  of  the  category  and  the  locale  arguments.  The  possible  values  for  | 
category  include:  | 

LC_CTYPE  | 

LC_COLLATE  | 

LC_TIME 

LC_NUMERIC  | 

LC_MONETARY 

Implementation-defined  additional  categories  | 

For  POSIX.l  systems,  environment  variables  are  defined  that  correspond  to  the  | 
named  categories  above  and  that  have  the  same  spelling.  | 

The  value  LC_ALL  for  category  names  all  of  the  categories  of  the  locale  of  the  pro-  | 
cess;  LC_ALL  is  a  special  constant,  not  a  category.  There  is  an  environment  vari-  | 
able  LC_ALL  with  the  semantics  noted  below.  | 

The  locale  argument  is  a  pointer  to  a  character  string  that  can  be  an  explicit  | 
string,  a  NULL  pointer,  or  a  null  string. 

When  locale  is  an  explicit  string,  the  contents  of  the  string  are  implementation  | 
defined  except  for  the  value  "C".  The  value  "C"  for  locale  specifies  the  minimal  | 
environment  for  C-language  translation.  If  setlocale ()  is  not  invoked,  the  "C"  | 

locale  shall  be  the  locale  of  the  process.  The  locale  name  "posix"  shall  be  recog-  | 
nized.  It  shall  provide  the  same  semantics  as  the  C  locale  for  those  functions  | 
defined  within  this  part  of  ISO/IEC  9945  or  by  the  C  Standard  {2}.  Extensions  or  | 
refinements  to  the  POSIX  locale  beyond  those  provided  by  the  C  locale  may  be  | 
included  in  future  revisions,  and  other  parts  of  ISO/IEC  9945  are  expected  to  add  | 
to  the  requirements  of  the  POSIX  locale. 

When  locale  is  a  NULL  pointer  the  locale  of  the  process  is  queried  according  to  the  | 
value  of  category.  The  content  of  the  string  returned  is  unspecified.  | 

When  locale  is  a  null  string,  the  setlocaleO  function  takes  the  name  of  the  new  | 
locale  for  the  specified  category  from  the  environment  as  determined  by  the  first  | 
condition  met  below:  I 

(1)  If  LC_ALL  is  defined  in  the  environment  and  is  not  null,  the  value  of  | 

LC_ALL  is  used.  | 

(2)  If  there  is  a  variable  defined  in  the  environment  with  the  same  name  as  | 
the  category  and  that  is  not  null,  the  value  specified  by  that  environment  | 
variable  is  used. 
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(3)  If  LANG  is  defined  in  the  environment  and  is  not  null,  the  value  of  LANG 
is  used. 

If  the  resulting  value  is  a  supported  locale,  setlocale ()  sets  the  specified  category 
of  the  locale  of  the  process  to  that  value  and  returns  the  value  specified  below.  If 
the  value  does  not  name  a  supported  locale  (and  is  not  null),  setlocalei)  returns  a 
NULL  pointer,  and  the  locale  of  the  process  is  not  changed  by  this  function  call.  If 
no  nonnull  environment  variable  is  present  to  supply  a  value,  it  is  implementa¬ 
tion  defined  whether  setlocalei )  sets  the  specified  category  of  the  locale  of  the  pro¬ 
cess  to  a  systemwide  default  value  or  to  "C"  or  to  "posix".  The  possible  actual 
values  of  the  environment  variables  are  implementation  defined  and  should 
appear  in  the  system  documentation. 

Setting  all  of  the  categories  of  the  locale  of  the  process  is  similar  to  successively 
setting  each  individual  category  of  the  locale  of  the  process,  except  that  all  error 
checking  is  done  before  any  actions  are  performed.  To  set  all  the  categories  of  the 
locale  of  the  process,  setlocalei )  is  invoked  as: 

setlocale  (LC_ALL, 

In  this  case,  setlocalei)  first  verifies  that  the  values  of  all  the  environment  vari¬ 
ables  it  needs  according  to  the  precedence  above  indicate  supported  locales.  If  the 
value  of  any  of  these  environment-variable  searches  yields  a  locale  that  is  not  sup¬ 
ported  (and  nonnull),  the  setlocale ()  function  returns  a  NULL  pointer  and  the 
locale  of  the  process  is  not  changed.  If  all  environment  variables  name  supported 
locales,  setlocalei )  then  proceeds  as  if  it  had  been  called  for  each  category,  using 
the  appropriate  value  from  the  associated  environment  variable  or  from  the 
implementation-defined  default  if  there  is  no  such  value. 

8. 1.2.3  Returns 

A  successful  call  to  setlocale ()  returns  a  string  that  corresponds  to  the  locale  set. 
The  string  returned  is  such  that  “a  subsequent  call  with  that  string  and  its  associ¬ 
ated  category  will  restore  that  part  of  the  process’s  locale”  (C  Standard  {2}).  The 
string  returned  shall  not  be  modified  by  the  process,  but  may  be  overwritten  by  a 
subsequent  call  to  the  setlocale ()  function.  This  string  is  not  required  to  be  the 
value  of  the  environment  variable  used,  if  one  was  used. 


8.2  C  Language  Input/Output  Functions 

This  clause  describes  input/output  functions  of  the  C  Standard  {2}  and  their 
interactions  with  other  functions  defined  by  this  part  of  ISO/IEC  9945. 

All  functions  specified  in  the  C  Standard  {2}  as  operating  on  a  file  name  shall 
operate  on  a  pathname.  All  functions  specified  in  the  C  Standard  {2}  as  creating  a 
file  shall  do  so  as  if  they  called  the  creati )  function  with  a  value  appropriate  to  the 
C  language  function  for  the  path  argument  and  a  value  of 

S_I  RLISR  |  S _ IWUSR|  S_IRGRP  |  S_I  WGRP  |  S_I  ROTH  |  S_I  WOTH 

for  the  mode  argument. 
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199  The  type  FILE  and  the  terms  file  position  indicator  and  stream  are  those  defined  | 

200  by  the  C  Standard  {2}.  | 

201  A  stream  is  considered  local  to  a  single  process.  After  a  fork{)  call,  each  of  the 

202  parent  and  child  have  distinct  streams  that  share  an  open  file  description. 

203  8.2.1  Map  a  Stream  Pointer  to  a  File  Descriptor 

204  Function:  fileno{) 

205  8.2. 1.1  Synopsis 

206  #include  <stdio.h> 

207  int  fileno(FiLE  *  stream)  ; 

208  8.2. 1.2  Description 

209  The  filenoO  function  returns  the  integer  file  descriptor  associated  with  the  stream 

210  (see  5.3.1). 

211  The  following  symbolic  values  in  the  <unistd.h>  header  (see  2.9)  define  the  file 

212  descriptors  that  shall  be  associated  with  the  C  language  stdin,  stdout,  and  stderr 

213  when  the  application  is  started: 

214  Name  _ Description _  Value 

215  STDIN_FILENO  Standard  input  value,  stdin.  0 

216  STDOUT_FILENO  Standard  output  value,  stdout.  1 

217  STDERR_FILENO  Standard  error  value,  stderr.  2 

218  At  entry  to  main{) ,  these  streams  shall  be  in  the  same  state  as  if  they  had  just  | 

219  been  opened  with  fdopen  ()  called  with  a  mode  consistent  with  that  required  by  | 

220  the  C  Standard  {2}  and  the  file  descriptor  described  above.  j 

221  8.2.1.3  Returns 

222  See  8.2. 1.2.  If  an  error  occurs,  a  value  of  -1  is  returned  and  errno  is  set  to  indi- 

223  cate  the  error. 

224  8.2. 1.4  Errors 

225  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

226  to  be  detected  for  the  filenoi )  function.  Some  errors  may  be  detected  under  condi-  | 

227  tions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  | 

228  8.2.1.5  Cross-References 

229  open  (),  5.3.1. 
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230  8.2.2  Open  a  Stream  on  a  File  Descriptor 

231  Function:  fdopen  () 


232  8.2.2. 1  Synopsis 

233  #include  <stdio.h> 

234  FILE  *fdopen(int  fildes ,  const  char  Hype); 


235  8.2.2.2  Description 

236  The  fdopen  f)  routine  associates  a  stream  with  a  file  descriptor. 

237  The  type  argument  is  a  character  string  having  one  of  the  following  values: 


238 

239 

240 

241 

242 

243 


"  r  "  Open  for  reading. 

"w"  Open  for  writing. 

"  a  "  Open  for  writing  at  end-of-file. 

"r+"  Open  for  update  (reading  and  writing). 

Mw+"  Open  for  update  (reading  and  writing). 

"a+"  Open  for  update  (reading  and  writing)  at  end-of-file. 


244  The  meaning  of  these  flags  is  exactly  as  specified  by  the  C  Standard  {2}  for 

245  fopen  (),  except  that  "w"  and  "w+"  do  not  cause  truncation  of  the  file.  Additional 

246  values  for  the  type  argument  may  be  defined  by  an  implementation. 

247  The  application  shall  ensure  that  the  mode  of  the  stream  is  allowed  by  the  mode  | 

248  of  the  open  file.  j 

249  The  file  position  indicator  associated  with  the  new  stream  is  set  to  the  position 

250  indicated  by  the  file  offset  associated  with  the  file  descriptor.  The  error  indicator  | 

251  and  end-of-file  indicator  for  the  stream  shall  be  cleared.  | 

252  | 


253  8.2.2.3  Returns 

254  If  successful,  the  fdopeni)  function  returns  a  pointer  to  a  stream.  Otherwise,  a 

255  NULL  pointer  is  returned  and  errno  is  set  to  indicate  the  error. 

256  8.2.2.4  Errors 

257  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

258  to  be  detected  for  the  fdopen  ()  function.  Some  errors  may  be  detected  under  con-  | 

259  ditions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  I 

260  8.2.2.5  Cross-References 

261  open(),  5.3.1;  fopen ()  [C  Standard  {2}]. 
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8.2.3  Interactions  of  Other  FILE- Type  C  Functions 

A  single  open  file  description  can  be  accessed  both  through  streams  and  through 
file  descriptors.  Either  a  file  descriptor  or  a  stream  will  be  called  a  handle  on  the 
open  file  description  to  which  it  refers;  an  open  file  description  may  have  several 
handles. 

Handles  can  be  created  or  destroyed  by  user  action  without  affecting  the  underly¬ 
ing  open  file  description.  Some  of  the  ways  to  create  them  include  fcntlO,  dupO, 
fdopenO,  filenoO,  and  forkO  (which  duplicates  existing  ones  into  new  processes). 
They  can  be  destroyed  by  at  least  fclose (),  close (),  and  the  exec  functions  (which 
close  some  file  descriptors  and  destroy  streams). 

A  file  descriptor  that  is  never  used  in  an  operation  that  could  affect  the  file  offset 
[for  example  readO,  write{),  or  Iseek ()]  is  not  considered  a  handle  in  this  discus¬ 
sion,  but  could  give  rise  to  one  [as  a  consequence  of  fdopenO,  dup  (),  or  fork  0,  for 
example].  This  exception  does  include  the  file  descriptor  underlying  a  stream, 
whether  created  with  fopenO  or  fdopenO,  as  long  as  it  is  not  used  directly  by  the 
application  to  affect  the  file  offset.  [The  readO  and  writeO  functions  implicitly 
affect  the  file  offset;  Iseek ()  explicitly  affects  it.] 

The  result  of  function  calls  involving  any  one  handle  (the  active  handle)  are 
defined  elsewhere  in  this  part  of  ISO/IEC  9945,  but  if  two  or  more  handles  are 
used,  and  any  one  of  them  is  a  stream,  their  actions  shall  be  coordinated  as 
described  below.  If  this  is  not  done,  the  result  is  undefined. 

A  handle  that  is  a  stream  is  considered  to  be  closed  when  either  an  fclose ()  or  freo- 
penO  is  executed  on  it  [the  result  of  freopen ()  is  a  new  stream  for  this  discussion, 
which  cannot  be  a  handle  on  the  same  open  file  description  as  its  previous  value] 
or  when  the  process  owning  that  stream  terminates  with  exitO  or  abortO.  A  file 
descriptor  is  closed  by  closeO,  jexitO,  or  by  one  of  the  exec  functions  when 
FD_CLOEXEC  is  set  on  that  file  descriptor. 

For  a  handle  to  become  the  active  handle,  the  actions  below  must  be  performed 
between  the  last  other  use  of  the  first  handle  (the  current  active  handle)  and  the 
first  other  use  of  the  second  handle  (the  future  active  handle).  The  second  handle 
then  becomes  the  active  handle.  All  activity  by  the  application  affecting  the  file 
offset  on  the  first  handle  shall  be  suspended  until  it  again  becomes  the  active  han¬ 
dle.  (If  a  stream  function  has  as  an  underlying  function  that  affects  the  file  offset, 
the  stream  function  will  be  considered  to  affect  the  file  offset.  The  underlying 
functions  are  described  below.) 

The  handles  need  not  be  in  the  same  process  for  these  rules  to  apply.  Note  that 
after  a  forkO,  two  handles  exist  where  one  existed  before.  The  application  shall 
assure  that,  if  both  handles  will  ever  be  accessed,  that  they  will  both  be  in  a  state 
where  the  other  could  become  the  active  handle  first.  The  application  shall 
prepare  for  a  forkO  exactly  as  if  it  were  a  change  of  active  handle.  [If  the  only 
action  performed  by  one  of  the  processes  is  one  of  the  exec  functions  or  _exitO  (not 
exit ()},  the  handle  is  never  accessed  in  that  process.] 

(1)  For  the  first  handle,  the  first  applicable  condition  below  shall  apply. 
After  the  actions  required  below  are  taken,  the  handle  may  be  closed  if  it 
is  still  open. 
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(a)  If  it  is  a  file  descriptor,  no  action  is  required. 

(b)  If  the  only  further  action  to  be  performed  on  any  handle  to  this  open 
file  description  is  to  close  it,  no  action  need  be  taken. 

(c)  If  it  is  a  stream  that  is  unbuffered,  no  action  need  be  taken. 

(d)  If  it  is  a  stream  that  is  line-buffered  and  the  last  character  written  | 

to  the  stream  was  a  newline  [that  is,  as  if  a  putc('  \  n' )  was  the  | 
most  recent  operation  on  that  stream],  no  action  need  be  taken.  | 

(e)  If  it  is  a  stream  that  is  open  for  writing  or  append  (but  not  also  open 
for  reading),  either  an  fflushi)  shall  occur  or  the  stream  shall  be 
closed. 

(f)  If  the  stream  is  open  for  reading  and  it  is  at  the  end  of  the  file 
[feof{ )  is  true],  no  action  need  be  taken. 

(g)  If  the  stream  is  open  with  a  mode  that  allows  reading  and  the 
underlying  open  file  description  refers  to  a  device  that  is  capable  of 
seeking,  either  an  fflushi)  shall  occur  or  the  stream  shall  be  closed. 

(h)  Otherwise,  the  result  is  undefined. 

(2)  For  the  second  handle:  if  any  previous  active  handle  has  called  a  func¬ 
tion  that  explicitly  changed  the  file  offset,  except  as  required  above  for 
the  first  handle,  the  application  shall  perform  an  Iseek ()  or  an  fseek ()  (as 
appropriate  to  the  type  of  the  handle)  to  an  appropriate  location. 

(3)  If  the  active  handle  ceases  to  be  accessible  before  the  requirements  on  the 
first  handle  above  have  been  met,  the  state  of  the  open  file  description 
becomes  undefined.  This  might  occur,  for  example,  during  a  forki)  or  an 
_exit(). 

(4)  The  exec  functions  shall  be  considered  to  make  inaccessible  all  streams 
that  are  open  at  the  time  they  are  called,  independent  of  what  streams  or 
file  descriptors  may  be  available  to  the  new  process  image. 

(5)  Implementations  shall  assure  that  an  application,  even  one  consisting  of 
several  processes,  shall  yield  correct  results  (no  data  is  lost  or  duplicated 
when  writing,  all  data  is  written  in  order,  except  as  requested  by  seeks) 
when  the  rules  above  are  followed,  regardless  of  the  sequence  of  handles 
used.  If  the  rules  above  are  not  followed,  the  result  is  unspecified.  When  | 
these  rules  are  followed,  it  is  implementation  defined  whether,  and  under  | 
what  conditions,  all  input  is  seen  exactly  once. 

(6)  Each  function  that  operates  on  a  stream  is  said  to  have  zero  or  more 
underlying  functions.  This  means  that  the  stream  function  shares  cer¬ 
tain  traits  with  the  underlying  functions,  but  does  not  require  that  there 
be  any  relation  between  the  implementations  of  the  stream  function  and 
its  underlying  functions. 

(7)  Also,  in  the  subclauses  below,  additional  requirements  on  the  standard  | 
I/O  routines,  beyond  those  in  the  C  Standard  [2],  are  given. 
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8.2.3.1  fopen  () 

The  fopen ( )  function  shall  allocate  a  file  descriptor  as  open()  does.  | 

The  underlying  function  is  openi). 

5.2.3.2  fclose  () 

The  fclose ()  function  shall  perform  a  close  ()  on  the  file  descriptor  that  is  associ-  | 
ated  with  the  FILE  stream.  It  shall  also  mark  for  update  the  stjctime  and 
stjntime  fields  of  the  underlying  file,  if  the  stream  was  writable,  and  if  buffered 
data  had  not  been  written  to  the  file  yet. 

The  underlying  functions  are  write  ( )  and  close  ( ). 


5.2.3.3  freopen  () 

The  freopen  ( )  function  has  the  properties  of  both  fclosei )  and  fopen  ( ).  | 

5.2.3.4  /flush  i) 

The  fflushi)  function  shall  mark  for  update  the  stjctime  and  stjntime  fields  of  the  | 
underlying  file  if  the  stream  was  writable  and  if  buffered  data  had  not  been  writ¬ 
ten  to  the  file  yet. 

The  underlying  functions  are  write  ()  and  Iseek  (). 


8.2.3.5  fgetc  ( ),  fgets  ( ),  fread ( ),  getc  ( ),  getchari ),  gets  ( ),  scanfi ),  f scanfi ) 

These  functions  may  mark  the  stjitime  field  for  update.  The  stjatime  field  shall 
be  marked  for  update  by  the  first  successful  execution  of  one  of  these  functions 
that  returns  data  not  supplied  by  a  prior  call  to  ungetc (). 

The  underlying  functions  are  readi)  and  Iseek (). 

8.2.5.6  fputci) ,  fputsOy  fwritei),  putci),  putchari),  putsi),  printfi), 

f printfi)  j 

The  stjctime  and  stjntime  fields  of  the  file  shall  be  marked  for  update  between 
the  successful  execution  of  one  of  these  functions  and  the  next  successful  comple¬ 
tion  of  a  call  to  either  fflushi)  or  fclose  ()  on  the  same  stream  or  a  call  to  exit( )  or 
abort  (). 

The  underlying  functions  are  write  ()  and  Iseek  (). 

If  fwritei. )  writes  greater  than  zero  bytes,  but  fewer  than  requested,  the  error  indi-  | 
cator  for  the  stream  shall  be  set.  If  the  underlying  write i)  reports  an  error,  errno  | 
shall  not  be  modified  by  fwritei),  and  the  error  indicator  for  the  stream  shall  be  | 
set. 
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382  If  the  implementation  provides  the  vprintfi )  and  ufprintfi )  functions  from  the  C  | 

383  Standard  {2},  they  also  shall  meet  the  constraints  specified  in  this  part  of  | 

384  ISO/IEC  9945  for  (respectively)  printfi )  and  fprintfi ).  | 

385  8.2.3.7  fseekOy  rewind  O 

386  These  functions  shall  mark  the  stjctime  and  stjntime  fields  of  the  file  for  update 

387  if  the  stream  was  writable  and  if  buffered  data  had  not  yet  been  written  to  the 

388  file. 

389  The  underlying  functions  are  IseekO  and  write ( ). 

390  If  the  most  recent  operation,  other  than  ftellO,  on  a  given  stream  is  fflushO,  the 

391  file  offset  in  the  underlying  open  file  description  shall  be  adjusted  to  reflect  the 

392  location  specified  by  the  fseek  ( ). 

393  8.2.3.8  perror () 

394  The  perror ()  function  shall  mark  the  file  associated  with  the  standard  error  | 

395  stream  as  having  been  written  ( stjctime ,  stjntime  marked  for  update)  at  some 

396  time  between  its  successful  completion  and  ex itO,  abortO,  or  the  completion  of 

397  f flush  ( )  or  f close  ( )  on  stderr . 

398  8.2.3.9  tmpfile  () 

399  The  tmpfile ()  function  shall  allocate  a  file  descriptor  as  fopenO  does. 

400  8.2.3.10  ftellO 

401  The  underlying  function  is  IseekO.  The  result  of  ftellO  after  an  fflushO  shall  be  | 

402  the  same  as  the  result  before  the  fflushO.  If  the  stream  is  opened  in  append  mode  | 

403  or  if  the  0_APPEND  flag  is  set  as  a  consequence  of  dealing  with  other  handles  on  | 

404  the  file,  the  result  of  ftelli )  on  that  stream  is  unspecified.  | 

405  8.2.3.11  Error  Reporting 

406  If  any  of  the  functions  above  return  an  error  indication,  the  value  of  errno  shall  be  | 

407  set  to  indicate  the  error  condition.  If  that  error  condition  is  one  that  this  part  of  | 

408  ISO/IEC  9945  specifies  to  be  detected  by  one  of  the  corresponding  underlying  func-  | 

409  tions,  the  value  of  errno  shall  be  the  same  as  the  value  specified  for  the  underly-  | 

410  ing  function.  I 

411  8.2.3.12  exitOy  abortO 

412  The  exitO  function  shall  have  the  effect  of  fc lose 0  on  every  open  stream,  with  the 

413  properties  of  fclose O  as  described  above.  The  abortO  function  shall  also  have 

414  these  effects  if  the  call  to  abortO  causes  process  termination,  but  shall  have  no  | 

415  effect  on  streams  otherwise.  The  C  Standard  {2}  specifies  the  conditions  where  | 

416  abortO  does  or  does  not  cause  process  termination.  For  the  purposes  of  that  | 

417  specification,  a  signal  that  is  blocked  shall  not  be  considered  caught. 
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418  8.2.4  Operations  on  Files  —  the  remove^)  Function 

419  The  remove ()  function  shall  have  the  same  effect  on  file  times  as  unlink{). 

420  8.3  Other  C  Language  Functions 

421  8.3.1  Nonlocal  Jumps 

422  Functions :  sigsetjmp  ( ),  siglongjmp  ( ) 

423  8.3. 1.1  Synopsis 

424  #include  <setjmp.h> 

425  int  sigsetjmp  (sigjmp_buf  env ,  int  savemask)  ; 

426  void  siglongjmp  (sigjmp_buf  env,  int  val)  ; 

427  8.3. 1.2  Description 

428  The  sigsetjmp  ()  macro  shall  comply  with  the  definition  of  the  setjmp  ( )  macro  in 

429  the  C  Standard  {2}.  If  the  value  of  the  savemask  argument  is  not  zero,  the  sig- 

430  setjmp  ()  function  shall  also  save  the  current  signal  mask  of  the  process  (see  3.3.1) 

431  as  part  of  the  calling  environment. 

432  The  siglongjmp  ()  function  shall  comply  with  the  definition  of  the  longjmp  ()  func- 

433  tion  in  the  C  Standard  {2}.  If  and  only  if  the  env  argument  was  initialized  by  a 

434  call  to  the  sigsetjmp  ()  function  with  a  nonzero  savemask  argument,  the 

435  siglongjmp ()  function  shall  restore  the  saved  signal  mask. 

436  8.3.1.3  Cross-References 

437  sigactionO,  3.3.4;  <signal.h>,  3.3.1;  sigprocmaskO,  3.3.5;  sigsuspendO,  3.3.7. 

438  8.3.2  Set  Time  Zone 

439  Function:  tzset () 

440  8.3.2.1  Synopsis 

441  tinclude  <time.h> 

442  void  tzset  (void)  ; 

443  8.3.2.2  Description 

444  The  tzset ()  function  uses  the  value  of  the  environment  variable  TZ  to  set  time 

445  conversion  information  used  by  localtime (),  dime (),  strftimei),  and  mktime().  If 

446  TZ  is  absent  from  the  environment,  implementation-defined  default  time-zone 

447  information  shall  be  used. 
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448  The  tzset( )  function  shall  set  the  external  variable  tzname : 

449  extern  char  *tzname[2]  =  {"std" ,  "dst"  }  ; 

450  where  std  and  dst  are  as  described  in  8.1.1. 
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Section  9:  System  Databases 

9.1  System  Databases 

The  routines  described  in  this  section  allow  an  application  to  access  the  two  sys¬ 
tem  databases  that  are  described  below. 

The  group  database  contains  the  following  information  for  each  group: 

(1)  Group  name 

(2)  Numerical  group  ID 

(3)  List  of  all  users  allowed  in  the  group  | 

The  user  database  contains  the  following  information  for  each  user: 

(1)  Username  | 

(2)  Numerical  user  ID 

(3)  Numerical  group  ID 

(4)  Initial  working  directory 

(5)  Initial  user  program 

If  the  initial  user  program  field  is  null,  the  system  default  is  used. 

If  the  initial  working  directory  field  is  null,  the  interpretation  of  that  field  is 
implementation  defined. 

These  databases  may  contain  other  fields  that  are  unspecified  by  this  part  of  | 
ISO/IEC  9945.  | 
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19  9.2  Database  Access 

20  9.2.1  Group  Database  Access 

21  Functions:  getgrgidO,  getgrnamO 

22  9.2. 1.1  Synopsis 

23  tinclude  <sys/types . h> 

24  #include  <grp.h> 

25  struct  group  *getgrgid  (gid_t  gid)  ; 

26  struct  group  *getgrnam (const  char  *name)  ; 

27  9.2. 1.2  Description 

28  The  getgrgidO  and  getgrnamO  routines  both  return  pointers  to  an  object  of  type 

29  struct  group  containing  an  entry  from  the  group  database  with  a  matching  gid  or 

30  name.  This  structure,  which  is  defined  in  <grp  .  h>,  includes  the  members  shown 

31  in  Table  9-1. 


32  Table  9=1  -  group  Structure 

33  _ 


34 

35 

Member 

Type 

Member 

Name 

Description 

36 

char  * 

grjiame 

The  name  of  the  group. 

37 

gid_t 

gr_gid 

The  numerical  group  ID. 

38 

char  ** 

gr_mem 

A  null-terminated  vector  of  pointers  to  the  individual  member  names. 

39 

40  9.2. 1.3  Returns 

41  A  NULL  pointer  is  returned  on  error  or  if  the  requested  entry  is  not  found. 

42  The  return  values  may  point  to  static  data  that  is  overwritten  by  each  call. 

43  9.2. 1.4  Errors 

44  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

45  to  be  detected  for  the  getgrgidO  or  getgrnamO  functions.  Some  errors  may  be  | 

46  detected  under  conditions  that  are  unspecified  by  this  part  of  ISO/IEC  9945.  | 

47  9.2.1.5  Cross-References 

48  getloginO,  4.2.4. 
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49  9.2.2  User  Database  Access 

50  Functions:  getpwuidO,  getpwnami.) 

51  9.2.2.1  Synopsis 

52  tinclude  <sys/types .h> 

53  tinclude  <pwd.h> 

54  struct  passwd  *getpwuid  (uid_t  uid)  ; 

55  struct  passwd  *getpwnam (const  char  *name)  ; 

56  9.2.2.2  Description 

57  The  getpwuid ()  and  getpwnam ()  functions  both  return  a  pointer  to  an  object  of 

58  type  struct  passwd  containing  an  entry  from  the  user  database  with  a  matching 

59  uid  or  name.  This  structure,  which  is  defined  in  <pwd .  h>,  includes  the  members 

60  shown  in  Table  9-2. 


61  Table  9-2  -  passwd  Structure 

62  _ 


63 

Member 

Member 

Description 

64 

Type 

Name 

65 

char  * 

pw_name 

User  name. 

66 

uidjt 

pw_uid 

User  ED  number. 

67 

gidjt 

pw_gid 

Group  ID  number. 

68 

char  * 

pw_dir 

Initial  Working  Directory. 

69 

char  * 

pwjshell 

Initial  User  Program. 

70 


72  9.2.2.3  Returns 

73  A  NULL  pointer  is  returned  on  error  or  if  the  requested  entry  is  not  found. 

74  The  return  values  may  point  to  static  data  that  is  overwritten  on  each  call. 

75  9.2.2.4  Errors 

76  This  part  of  ISO/IEC  9945  does  not  specify  any  error  conditions  that  are  required 

77  to  be  detected  for  the  getpwuidO  or  getpwnam ()  functions.  Some  errors  may  be  | 

78  detected  under  conditions  that  are  unspecified  by  this  part  of  ISO/IEC  9945. 

79  9.2.2.5  Cross-References 

so  getlogin  (),  4.2.4.  I 
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Section  10:  Data  Interchange  Format 


10.1  Archive/Interchange  File  Format 

A  conforming  system  shall  provide  a  mechanism  to  copy  files  from  a  medium  to 
the  file  hierarchy  and  copy  files  from  the  file  hierarchy  to  a  medium  using  the 
interchange  formats  described  here.  This  part  of  ISO/IEC  9945  does  not  define 
this  mechanism. 

When  this  mechanism  is  used  to  copy  files  from  the  medium  by  a  process  without 
appropriate  privileges,  the  protection  information  (ownership  and  access  permis¬ 
sions)  shall  be  set  in  the  same  fashion  that  creat ()  would  when  given  the  mode 
argument  matching  the  file  permissions  supplied  by  the  mode  field  of  the 
extended  tar  format  or  the  cjnode  field  of  the  extended  cpio  format.  A  process 
with  appropriate  privileges  shall  restore  the  ownership  and  the  permissions 
exactly  as  recorded  on  the  medium,  except  that  the  symbolic  user  and  group  IDs 
are  used  for  the  tar  format,  as  described  in  10.1.1. 

The  format-creating  utility  is  used  to  translate  from  the  file  system  to  the  formats  | 
defined  in  this  clause.  The  format-reading  utility  is  used  to  translate  from  the  for-  | 
mats  defined  in  this  clause  to  a  file  system.  The  interface  to  these  utilities,  | 
including  their  name  or  names,  is  implementation  defined.  | 

The  headers  of  these  formats  are  defined  to  use  characters  represented  in  | 
ISO/IEC  646  {1};  however,  no  restrictions  are  placed  on  the  contents  of  the  files  | 
themselves.  The  data  in  a  file  may  be  binary  data  or  text  represented  in  any  for¬ 
mat  available  to  the  user.  When  these  formats  are  used  to  transfer  text  at  the 
source  level,  all  characters  shall  be  represented  in  ISO/IEC  646  {1}  International  | 
Reference  Version  (IRV).  I 

The  media  format  and  the  frames  on  the  media  in  which  the  data  appear  are  | 
unspecified  by  this  part  of  ISO/IEC  9945.  I 

NOTE:  Guidelines  are  given  in  Annex  B. 


10.1.1  Extended  tar  Format 

An  extended  tar  archive  tape  or  file  contains  a  series  of  blocks.  Each  block  is  a 
fixed-size  block  of  512  bytes  (see  below).  Although  this  format  may  be  thought  of 
as  being  stored  on  9-track  industry-standard  12,7  mm  (0,5  in)  magnetic  tape,  | 
other  types  of  transportable  media  are  not  excluded.  Each  file  archived  is 
represented  by  a  header  block  that  describes  the  file,  followed  by  zero  or  more 
blocks  that  give  the  contents  of  the  file.  At  the  end  of  the  archive  file  are  two 
blocks  filled  with  binary  zeroes,  interpreted  as  an  end-of-archive  indicator. 
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The  blocks  may  be  grouped  for  physical  I/O  operations.  Each  group  of  n  blocks 
(where  n  is  set  by  the  application  utility  creating  the  archive  file)  may  be  written 
with  a  single  write()  operation.  On  magnetic  tape,  the  result  of  this  write  is  a  sin¬ 
gle  tape  record.  The  last  group  of  blocks  is  always  at  the  full  size,  so  blocks  after 
the  two  zero  blocks  contain  undefined  data. 

The  header  block  is  structured  as  shown  in  Table  10-1.  All  lengths  and  offsets  are 
in  decimal. 


Table  10-1  -  tar  Header  Block 


Field  Name 

Byte  Offset 

Length  (in  bytes) 

name 

0 

100 

mode 

100 

8 

uid 

108 

8 

gid 

116 

8 

size 

124 

12 

mtime 

136 

12 

chksum 

148 

8 

typeflag 

156 

1 

linkname 

157 

100 

magic 

257 

6 

version 

263 

2 

uname 

265 

32 

gname 

297 

32 

devmajor 

329 

8 

devminor 

337 

8 

prefix 

345 

155 

Symbolic  constants  used  in  the  header  block  are  defined  in  the  header  <tar .  h> 
as  follows: 


#def ine 

TMAGIC 

"ustar" 

/* 

ustar  and  a  null  */ 

#def ine 

TMAGLEN 

6 

#def ine 

TVERSION 

o 

o 

/* 

00  and  no  null  */ 

#def ine 

TVERSLEN 

2 

/*  Values  used  in  typeflag 

field  */ 

#def ine 

REGTYPE 

'0' 

/* 

Regular  file 

*/ 

#def ine 

AREGTYPE 

'  \0' 

/* 

Regular  file 

*/ 

#def ine 

LNKTYPE 

'  1' 

/* 

Link 

*/ 

♦define 

SYMTYPE 

'2' 

/* 

Reserved 

*/ 

♦define 

CHRTYPE 

'3' 

/* 

Character  special  */ 

♦define 

BLKTYPE 

'4' 

/* 

Block  special 

*/ 

♦define 

DIRTYPE 

'  5' 

/* 

Directory 

*/ 

♦define 

FIFOTYPE 

'  6' 

/* 

FIFO  special 

*/ 

♦define 

CONTTYPE 

'  7 ' 

/* 

Reserved 

*/ 

/*  Bits 

used  in 

the  mode 

field  -  values  in  octa' 

♦define 

TSUID 

04  000 

/* 

Set  UID  on  execution 

♦define 

TSGID 

02  000 

/* 

Set  GID  on  execution 

♦define 

TSVTX 

01000 

/* 

Reserved  */ 

/*  File  permissions  */ 
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#def ine 

TUREAD 

00  400 

/* 

Read  by  owner  * 

/ 

#def ine 

TUWRITE 

00  200 

/* 

Write  by  owner 

*/ 

#def ine 

TUEXEC 

00  100 

/* 

Execute /Search 

by 

owner 

*/ 

#def ine 

TGREAD 

00  040 

/* 

Read  by  group  * 

/ 

#def ine 

TGWRITE 

00  020 

/* 

Write  by  group 

*/ 

#def ine 

TGEXEC 

00  010 

/* 

Execute/ Search 

by 

group 

*/ 

#def ine 

TOREAD 

00  004 

/* 

Read  by  other  */ 

#def ine 

TOWRITE 

00  002 

/* 

Write  by  other 

*/ 

#def ine 

TOEXEC 

00  001 

/* 

Execute/ Search 

by 

other 

*/ 

All  characters  are  represented  in  the  coded  character  set  of  ISO/IEC  646  {1}.  For  | 
maximum  portability  between  implementations,  names  should  be  selected  from 
characters  represented  by  the  portable  filename  character  set  as  8-bit  characters 
with  most  significant  bit  zero.  If  an  implementation  supports  the  use  of  charac-  | 
ters  outside  the  portable  filename  character  set  in  names  for  files,  users,  and  | 
groups,  one  or  more  implementation-defined  encodings  of  these  characters  shall  | 
be  provided  for  interchange  purposes.  However,  the  format-reading  utility  shall  | 
never  create  file  names  on  the  local  system  that  cannot  be  accessed  via  the  func¬ 
tions  described  previously  in  this  part  of  ISO/IEC  9945;  see  5.3.1,  5.6.2,  5.2.1, 
6.5.2,  and  5.1.2.  If  a  file  name  is  found  on  the  medium  that  would  create  an 
invalid  file  name,  the  implementation  shall  define  if  the  data  from  the  file  is 
stored  on  the  file  hierarchy  and  under  what  name  it  is  stored.  A  format-reading 
utility  may  choose  to  ignore  these  files  as  long  as  it  produces  an  error  indicating 
that  the  file  is  being  ignored. 

Each  field  within  the  header  block  is  contiguous;  that  is,  there  is  no  padding  used. 
Each  character  on  the  archive  medium  is  stored  contiguously. 

The  fields  magic,  uname,  and  gname  are  null- terminated  character  strings.  The 
fields  name,  linkname,  and  prefix  are  null-terminated  character  strings  except 
when  all  characters  in  the  array  contain  nonnull  characters  including  the  last 
character.  The  version  field  is  two  bytes  containing  the  characters  "00"  (zero- 
zero).  The  typeflag  contains  a  single  character.  All  other  fields  are  leading  zero- 
filled  octal  numbers  using  digits  from  ISO/IEC  646  {1}  IRV.  Each  numeric  field  is  | 
terminated  by  one  or  more  space  or  null  characters. 

The  name  and  the  prefix  fields  produce  the  pathname  of  the  file.  The  hierarchical 
relationship  of  the  file  is  retained  by  specifying  the  pathname  as  a  path  prefix, 
and  a  slash  character  and  filename  as  the  suffix.  A  new  pathname  is  formed,  if  | 
prefix  is  not  an  empty  string  (its  first  character  is  not  null),  by  concatenating  | 
prefix  (up  to  the  first  null  character),  a  slash  character,  and  name',  otherwise,  | 
name  is  used  alone.  In  either  case,  name  is  terminated  at  the  first  null  character.  | 
If  prefix  is  an  empty  string,  it  is  simply  ignored.  In  this  manner,  pathnames  of  at  | 
most  256  characters  can  be  supported.  If  a  pathname  does  not  fit  in  the  space 
provided,  the  format-creating  utility  shall  notify  the  user  of  the  error,  and  no 
attempt  shall  be  made  by  the  format-creating  utility  to  store  any  part  of  the  file — 
header  or  data — on  the  medium. 

The  linkname  field,  described  below,  does  not  use  the  prefix  to  produce  a  path¬ 
name.  As  such,  a  linkname  is  limited  to  100  characters.  If  the  name  does  not  fit  | 
in  the  space  provided,  the  format-creating  utility  shall  notify  the  user  of  the  error, 
and  the  utility  shall  not  attempt  to  store  the  link  on  the  medium. 
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The  mode  field  provides  9  bits  specifying  file  permissions  and  3  bits  to  specify  the 
set  UID,  set  GID,  and  TSVTX  modes.  Values  for  these  bits  were  defined  previously. 
When  appropriate  privilege  is  required  to  set  one  of  these  mode  bits,  and  the  user 
restoring  the  files  from  the  archive  does  not  have  the  appropriate  privilege,  the 
mode  bits  for  which  the  user  does  not  have  appropriate  privilege  shall  be  ignored. 
Some  of  the  mode  bits  in  the  archive  format  are  not  mentioned  elsewhere  in  this 
part  of  ISO/IEC  9945.  If  the  implementation  does  not  support  those  bits,  they  may 
be  ignored. 

The  uid  and  gid  fields  are  the  user  and  group  ID  of  the  owner  and  group  of  the 
file,  respectively. 

The  size  field  is  the  size  of  the  file  in  bytes.  If  the  typeflag  field  is  set  to  specify  a 
file  to  be  of  type  LNKTYPE  or  SYMTYPE,  the  size  field  shall  be  specified  as  zero.  If 
the  typeflag  field  is  set  to  specify  a  file  of  type  DIRTYPE,  the  size  field  is  inter¬ 
preted  as  described  under  the  definition  of  that  record  type.  No  data  blocks  are  | 
stored  for  LNKTYPE,  SYMTYPE,  or  DIRTYPE.  If  the  typeflag  field  is  set  to  | 
CHRTYPE,  BLKTYPE,  or  FIFOTYPE,  the  meaning  of  the  size  field  is  unspecified  by  | 
this  part  of  ISO/IEC  9945,  and  no  data  blocks  are  stored  on  the  medium.  Addition-  | 
ally,  for  FIFOTYPE,  the  size  field  shall  be  ignored  when  reading.  If  the  typeflag  \ 
field  is  set  to  any  other  value,  the  number  of  blocks  written  following  the  header 
is  (size+ 511)/512,  ignoring  any  fraction  in  the  result  of  the  division. 

The  mtime  field  is  the  modification  time  of  the  file  at  the  time  it  was  archived.  It 
is  the  ISO/IEC  646  {1}  representation  of  the  octal  value  of  the  modification  time  | 
obtained  from  the  stat()  function. 

The  chksum  field  is  the  ISO/IEC  646  {1}  IRV  representation  of  the  octal  value  of  | 
the  simple  sum  of  all  bytes  in  the  header  block.  Each  8-bit  byte  in  the  header  is 
treated  as  an  unsigned  value.  These  values  are  added  to  an  unsigned  integer,  ini¬ 
tialized  to  zero,  the  precision  of  which  shall  be  no  less  than  17  bits.  When  calcu¬ 
lating  the  checksum,  the  chksum  field  is  treated  as  if  it  were  all  blanks. 

The  typeflag  field  specifies  the  type  of  file  archived.  If  a  particular  implementa¬ 
tion  does  not  recognize  the  type,  or  the  user  does  not  have  appropriate  privilege  to 

create  that  type,  the  file  shall  be  extracted  as  if  it  were  a  regular  file  if  the  file 
type  is  defined  to  have  a  meaning  for  the  size  field  that  could  cause  data  blocks  to 
be  written  on  the  medium  (see  the  previous  description  for  size).  If  conversion  to 
an  ordinary  file  occurs,  the  format-reading  utility  shall  produce  an  error  indicat¬ 
ing  that  the  conversion  took  place.  All  of  the  typeflag  fields  are  coded  in  \ 
ISO/IEC  646  {1}  IRV:  I 

'  0 '  Represents  a  regular  file.  For  backward  compatibility,  a  typeflag  | 

value  of  binary  zero  ( '  \  0 ' )  should  be  recognized  as  meaning  a  regu¬ 
lar  file  when  extracting  files  from  the  archive.  Archives  written 
with  this  version  of  the  archive  file  format  shall  create  regular  files 
with  a  typeflag  value  of  ISO/IEC  646  {1}  IRV  'O'.  \ 

'  1 '  Represents  a  file  linked  to  another  file,  of  any  type,  previously  | 

archived.  Such  files  are  identified  by  each  file  having  the  same  dev¬ 
ice  and  file  serial  number.  The  linked-to  name  is  specified  in  the  | 
linkname  field  with  a  null  terminator  if  it  is  less  than  100  bytes  in  | 
length. 
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'  2 '  Reserved  to  represent  a  link  to  another  file,  of  any  type,  whose  dev-  | 

ice  or  file  serial  number  differs.  This  is  provided  for  systems  that 
support  linked  files  whose  device  or  file  serial  numbers  differ,  and 
should  be  treated  as  a  type  '  1 '  file  if  this  extension  does  not  exist. 

'  3 '  ,  '  4 '  Represent  character  special  files  and  block  special  files  respectively.  | 
In  this  case  the  devmajor  and  devminor  fields  shall  contain  informa-  | 
tion  defining  the  device,  the  format  of  which  is  unspecified  by  this  | 
part  of  ISO/IEC  9945.  Implementations  may  map  the  device  | 
specifications  to  their  own  local  specification  or  may  ignore  the 
entry. 

'  5 '  Specifies  a  directory  or  subdirectory.  On  systems  where  disk  alloca-  | 

tion  is  performed  on  a  directory  basis,  the  size  field  shall  contain  the 
maximum  number  of  bytes  (which  may  be  rounded  to  the  nearest 
disk  block  allocation  unit)  that  the  directory  may  hold.  A  size  field 
of  zero  indicates  no  such  limiting.  Systems  that  do  not  support  lim¬ 
iting  in  this  manner  should  ignore  the  size  field. 

'  6 '  Specifies  a  FIFO  special  file.  Note  that  the  archiving  of  a  FIFO  file  | 

archives  the  existence  of  this  file  and  not  its  contents. 

'  7 '  Reserved  to  represent  a  file  to  which  an  implementation  has  associ-  | 

ated  some  high  performance  attribute.  Implementations  without 
such  extensions  should  treat  this  file  as  a  regular  file  (type  '  0 ' ). 

'A'  Z'  The  letters  A  through  Z  are  reserved  for  custom  implementations.  | 
All  other  values  are  reserved  for  specification  in  future  revisions  of 
this  part  of  ISO/IEC  9945. 

The  magic  field  is  the  specification  that  this  archive  was  output  in  this  archive 
format.  If  this  field  contains  TMAGIC,  the  uname  and  gname  fields  shall  contain 
the  ISO/IEC  646  {1}  IRV  representation  of  the  owner  and  group  of  the  file  respec-  | 
tively  (truncated  to  fit,  if  necessary).  When  the  file  is  restored  by  a  privileged, 
protection-preserving  version  of  the  utility,  the  password  and  group  files  shall  be 
scanned  for  these  names.  If  found,  the  user  and  group  IDs  contained  within  these 
files  shall  be  used  rather  than  the  values  contained  within  the  uid  and  gid  fields. 

The  encoding  of  the  header  is  designed  to  be  portable  across  machines. 

10.1.1.1  Cross-References 

<grp .  h>,  9.2.1;  <pwd.h>,  9.2.2;  <sys/stat .  h>,  5.6.1;  stat(),  5.6.2; 

<unistd.h>,  2.9. 


10.1.2  Extended  cpio  Format 

The  byte-oriented  cpio  archive  format  is  a  series  of  entries,  each  comprised  of  a 
header  that  describes  the  file,  the  name  of  the  file,  and  then  the  contents  of  the 
file. 

An  archive  may  be  recorded  as  a  series  of  fixed-size  blocks  of  bytes.  This  blocking 
shall  be  used  only  to  make  physical  I/O  more  efficient.  The  last  group  of  blocks  is 
always  at  the  full  size. 
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218  For  the  byte-oriented  cpio  archive  format,  the  individual  entry  information  must 

219  be  in  the  order  indicated  and  described  by  Table  10-2. 


220  Table  10-2  -  Byte-Oriented  cpio  Archive  Entry 

221  _ 


222 

Header 

223 

Field  Name 

Length  (in  bytes) 

Interpreted  as 

224 

cjnagic 

6 

Octal  number 

225 

cjdev 

6 

Octal  number 

226 

cjno 

6 

Octal  number 

227 

cjnode 

6 

Octal  number 

228 

cjiid 

6 

Octal  number 

229 

c_gid 

6 

Octal  number 

230 

cjilink 

6 

Octal  number 

231 

cj-dev 

6 

Octal  number 

232 

cjntime 

11 

Octal  number 

233 

cnamesize 

6 

Octal  number 

234 

c  _filesize 

11 

Octal  number 

235 

File  Name 

236 

Field  Name 

Length 

Interpreted  as 

237 

cjiame 

cjiamesize 

Pathname  string 

238 

File  Data 

239 

Field  Name 

Length 

Interpreted  as 

240 

c  Jiledata 

c  Jilesize 

Data 

241 

242  10.1.2.1  cpio  Header 


243  For  each  file  in  the  archive,  a  header  as  defined  previously  shall  be  written.  The 

244  information  in  the  header  fields  shall  be  written  as  streams  of  ISO/IEC  646  {1}  | 

245  characters  interpreted  as  octal  numbers.  The  octal  numbers  are  extended  to  the  | 

246  necessary  length  by  appending  ISO/IEC  646  {1}  IRV  zeros  at  the  most-significant-  | 

247  digit  end  of  the  number;  the  result  is  written  to  the  stream  of  bytes  most- 

248  significant-digit  first.  The  fields  shall  be  interpreted  as  follows: 


249  (1)  cjnagic  shall  identify  the  archive  as  being  a  transportable  archive  by 

250  containing  the  magic  bytes  as  defined  by  MAGIC  (070707). 


251 

252 

253 

254 


(2)  c_dev  and  c_ino  shall  contain  values  that  uniquely  identify  the  file  within 
the  archive  (i.e.,  no  files  shall  contain  the  same  pair  of  cjdeu  and  c_ino 
values  unless  they  are  links  to  the  same  file).  The  values  shall  be  deter¬ 
mined  in  an  unspecified  manner. 


255  (3)  cjnode  shall  contain  the  file  type  and  access  permissions  as  defined  in 

256  Table  10-3. 


257  (4)  c_uid  shall  contain  the  user  ID  of  the  owner. 

258  (5)  c_gid  shall  contain  the  group  ID  of  the  group. 
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259 

260 

Table  10-3 

-  Values  for  cpio  cjnode  Field 

261 

File  Permissions 

262 

Name 

Value 

Indicates 

263 

c_irusr 

000400 

Read  by  owner. 

264 

C_IWUSR 

000  200 

Write  by  owner. 

265 

CJXUSR 

000100 

Execute  by  owner. 

266 

C_DRGRP 

000  040 

Read  by  group. 

267 

C_IWGRP 

000  020 

Write  by  group. 

268 

C_IXGRP 

000  010 

Execute  by  group. 

269 

CJROTH 

000  004 

Read  by  others. 

270 

C_IWOTH 

000  002 

Write  by  others. 

271 

CJKOTH 

000  001 

Execute  by  others. 

272 

cjsum 

004  000 

Set  uid. 

273 

CJSGID 

002  000 

Set  gid. 

274 

C_ISVTX 

001000 

Reserved. 

275 

File  Type 

276 

Name 

Value 

Indicates 

277 

CJSDIR 

040  000 

Directory. 

278 

C_ISFIFO 

010  000 

FIFO. 

279 

C_ISREG 

0100  000 

Regular  file. 

280 

C_ISBLK 

060  000 

Block  special  file. 

281 

C_ISCHR 

020  000 

Character  special  file. 

282 

C_ISCTG 

0110  000 

Reserved. 

283 

C_ISLNK 

0120  000 

Reserved. 

284 

C_ISSOCK 

0140  000 

Reserved. 

285 

286 

287 

(6) 

cjilink  shall  contain  the  number  of  links  referencing  the  file  at  the  time 
the  archive  was  created. 

288 

289 

(7) 

c_rdeu  shall  contain  implementation-defined  information  for  character  or 
block  special  files. 

290 

291 

(8) 

cjntim.e  shall  contain  the  latest  time  of  modification  of  the  file  at  the 
time  the  archive  was  created. 

292 

293 

(9) 

cjiamesize  shall  contain  the  length  of  the  pathname,  including  the  ter¬ 
minating  null  byte. 

294 

295 

(10) 

c  Jilesize  shall  contain  the  length  of  the  file  in  bytes.  This  is  the  length  of 
the  data  section  following  the  header  structure. 

296 

10.1.2.2 

cpio  File  Name 

297 

cjiame 

shall  contain  the  pathname  of  the  file.  The  length  of  this  field  in  bytes  is 

298  the  value  of  cjiamesize .  If  a  file  name  is  found  on  the  medium  that  would  create 

299  an  invalid  pathname,  the  implementation  shall  define  if  the  data  from  the  file  is 

300  stored  on  the  file  hierarchy  and  under  what  name  it  is  stored. 
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All  characters  are  represented  in  ISO/IEC  646  {1}  IRV.  For  maximum  portability  | 
between  implementations,  names  should  be  selected  from  characters  represented  | 
by  the  portable  filename  character  set  as  8-bit  characters  most  significant  bit  zero.  | 
If  an  implementation  supports  the  use  of  characters  outside  the  portable  filename  j 
character  set  in  names  for  files,  users,  and  groups,  one  or  more  implementation-  | 
defined  encodings  of  these  characters  shall  be  provided  for  interchange  purposes.  | 
However,  the  format-reading  utility  shall  never  create  file  names  on  the  local  sys-  | 
tern  that  cannot  be  accessed  via  the  functions  described  previously  in  this  part  of 
ISO/IEC  9945;  see  open(),  stat(),  chdir(),  fcntl(),  and  opendir().  If  a  file  name  is 
found  on  the  medium  that  would  create  an  invalid  file  name,  the  implementation 
shall  define  if  the  data  from  the  file  is  stored  on  the  local  file  system  and  under 
what  name  it  is  stored.  A  format-reading  utility  may  choose  to  ignore  these  files 
as  long  as  it  produces  an  error  indicating  that  the  file  is  being  ignored. 

10.1.2.3  cpio  File  Data 

Following  cjiame,  there  shall  be  c  Jilesize  bytes  of  data.  Interpretation  of  such 
data  shall  occur  in  a  manner  dependent  on  the  file.  If  c  Jilesize  is  zero,  no  data 
shall  be  contained  in  c  Jiledata. 

10.1.2.4  cpio  Special  Entries 

FIFO  special  files,  directories,  and  the  trailer  are  recorded  with  c  Jilesize  equal  to 
zero.  For  other  special  files,  c  Jilesize  is  unspecified  by  this  part  of  ISO/IEC  9945.  | 

The  header  for  the  next  file  entry  in  the  archive  shall  be  written  directly  after  the 
last  byte  of  the  file  entry  preceding  it.  A  header  denoting  the  file  name 
“trailer!  !  !”  shall  indicate  the  end  of  the  archive;  the  contents  of  bytes  in  the 
last  block  of  the  archive  following  such  a  header  are  undefined. 

10.1.2.5  cpio  Values 

Values  needed  by  the  cpio  archive  format  are  described  in  Table  10-3. 

C_ISDIR,  C_ISFIFO,  and  C_ISREG  shall  be  supported  on  a  system  conforming  to 
this  part  of  ISO/IEC  9945;  additional  values  defined  previously  are  reserved  for 
compatibility  with  existing  systems.  Additional  file  types  may  be  supported;  how¬ 
ever,  such  files  should  not  be  written  on  archives  intended  for  transport  to  port¬ 
able  systems. 

C_ISVTX,  C.ISCTG,  C_ISLNK,  and  C_ISSOCK  have  been  reserved  by  this  part  of 
ISO/IEC  9945  to  retain  compatibility  with  some  existing  implementations. 

When  restoring  from  an  archive: 

(1)  If  the  user  does  not  have  the  appropriate  privilege  to  create  a  file  of  the 
specified  type,  the  format-interpreting  utility  shall  ignore  the  entry  and 
issue  an  error  to  the  standard  error  output. 

(2)  Only  regular  files  have  data  to  be  restored.  Presuming  a  regular  file 
meets  any  selection  criteria  that  might  be  imposed  on  the  format-reading 
utility  by  the  user,  such  data  shall  be  restored. 
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341  (3)  If  a  user  does  not  have  appropriate  privilege  to  set  a  particular  mode  flag, 

342  the  flag  shall  be  ignored.  Some  of  the  mode  flags  in  the  archive  format 

343  are  not  mentioned  elsewhere  in  this  part  of  ISO/IEC  9945.  If  the  imple- 

344  mentation  does  not  support  those  flags,  they  may  be  ignored. 

345  10.1.2.6  Cross-References 

346  <grp.h>,  9.2.1;  <pwd.h>,  9.2.2;  <sys/ stat . h>,  5.6.1;  chmod(),  5.6.4;  link(), 

347  5.3.4;  mkdirO,  5.4.1;  read{),  6.4.1;  stat(),  5.6.2. 


348  10.1.3  Multiple  Volumes 

349  It  shall  be  possible  for  data  represented  by  the  Archive/Interchange  File  Format 

350  to  reside  in  more  than  one  file. 

351  The  format  is  considered  a  stream  of  bytes.  An  end-of-file  (or  equivalently  an 

352  end-of-media)  condition  may  occur  between  any  two  bytes  of  the  logical  byte 

353  stream.  If  this  condition  occurs,  the  byte  following  the  end-of-file  will  be  the  first 

354  byte  on  the  next  file.  The  format-reading  utility  shall,  in  an  implementation- 

355  defined  manner,  determine  what  file  to  read  as  the  next  file. 
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(informative) 

Rationale  and  Notes 


The  Annex  is  being  published  as  an  informative  part  of  POSIX.l  to  assist  in  the  | 
process  of  review.  It  contains  historical  information  concerning  the  contents  of 
POSIX.1  and  why  features  were  included  or  discarded.  It  also  contains  notes  of  | 
interest  to  application  programmers  on  recommended  programming  practices, 
emphasizing  the  consequences  of  some  aspects  of  POSIX.l  that  may  not  be 
immediately  apparent. 1) 


B.l  Scope  and  Normative  References 


B.1.1  Scope 

This  Rationale  focuses  primarily  on  additions,  clarifications,  and  changes  made  to 
the  UNIX  system,  from  which  POSIX.l  was  derived.  It  is  not  a  rationale  for  the  | 
UNIX  system  as  a  whole,  since  the  goal  of  POSIX.l’s  developers  was  to  codify  exist-  | 
ing  practice,  not  design  a  new  operating  system.  No  attempt  is  made  in  this  | 
Rationale  to  defend  the  pre-existing  structure  of  UNIX  systems.  It  is  primarily 
deviations  from  existing  practice,  as  codified  in  the  base  documents,  that  are 
explained  or  justified  here. 

Material  that  is  “outside  the  scope”  or  otherwise  not  addressed  by  this  part  of 
ISO/IEC  9945  is  implicitly  “unspecified.”  It  may  be  included  in  an  implementa-  | 
tion,  and  thus  the  implementation  does  provide  a  specification  for  it.  The  term  | 
“implementation-defined”  has  a  specific  meaning  in  POSIX.1  and  is  not  a  synonym  | 
for  “defined  (or  specified)  by  the  implementation.” 

The  Rationale  discusses  some  UNIX  system  features  that  were  not  adopted  into 
POSIX.1.  Many  of  these  are  features  that  are  popular  in  some  UNIX  system  imple¬ 
mentations,  so  that  a  user  of  those  implementations  might  question  why  they  do 
not  appear  in  POSIX.l.  This  Rationale  should  provide  the  appropriate  answers. 


1)  The  material  in  this  annex  is  derived  in  part  from  copyrighted  draft  documents  developed  under 
the  sponsorship  of  UniForum,  as  part  of  an  ongoing  program  of  that  association  to  support  the 
POSIX  standards  program  efforts. 
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There  are  choices  allowed  by  POSIX.  1  for  some  details  of  the  interface 
specification;  some  of  these  are  specifiable  optional  subsets  of  POSIX.1.  See  B.2.9.  | 

Although  the  services  POSEX.l  provides  have  been  defined  in  the  C  language,  the 
concept  of  providing  fundamental,  standardized  services  should  not  be  restricted 
only  to  programs  of  a  particular  programming  language.  The  possibility  of  imple¬ 
menting  interfaces  in  alternate  programming  languages  inspired  the  term  | 
POSIX.1  with  the  C  Language  Binding.  The  word  Binding  refers  to  the  binding  of  | 
a  conceptual  set  of  services  and  a  standardized  C  interface  that  establishes  rules 
and  syntax  for  accessing  them.  Future  international  standards  are  expected  to  | 
separate  the  C  language  binding  from  the  language-independent  services  of  | 
POSIX.1  and  to  include  bindings  for  other  programming  languages.  | 

The  C  Standard  {2}  will  be  the  basis  for  functional  definitions  of  core  services  that  | 
are  independent  of  programming  languages.  POSIX.1  as  it  stands  now  can  be 
thought  of  as  a  C  Language  Binding.  Sections  1  through  7,  and  9,  correspond  | 
roughly  to  the  C  language  implementation  of  what  will  be  defined  in  the  program¬ 
ming  language-independent  core  services  portion  of  POSIX.1;  Section  8  | 

corresponds  to  the  C  language-specific  portion.  | 

The  criteria  used  to  choose  the  programming  language-independent  core  services 
may  be  different  from  those  expected.  The  core  services  represent  services  that 
are  common  to  those  programming  languages  likely  to  form  language  bindings  to 
POSIX.1 — the  greatest  common  denominator.  They  are  not  chosen  to  reflect  the 
most  important  system  services  of  an  ideal  operating  system.  For  this  reason, 
some  fundamental  system  services  are  not  included  in  the  language-independent  | 
core.  As  an  example,  memory  management  routines  would  at  first  seem  to  be  a  | 
core  service — they  are  an  absolutely  fundamental  system  service.  They  must, 
however,  be  included  in  language-specific  portions  of  POSIX.1  because  program¬ 
ming  languages  such  as  FORTRAN  have  traditionally  not  provided  memory 
management.  Categorizing  memory  management  as  a  core  service  would  impose 
unreasonable  requirements  for  FORTRAN  implementations. 

Any  programming  language  traditionally  supporting  memory  management  should 
include  those  routines  in  the  language-dependent  portions  of  their  bindings. 
Work  will  be  done  at  a  later  time  to  standardize  the  classes  of  functions  that  must 
be  included  in  the  language-dependent  portions  of  language  bindings  if  those 
functions  have  been  traditionally  implemented  for  that  language.  This  will 
ensure  that  certain  classes  of  critical  functions,  such  as  memory  management, 
will  not  be  excluded  from  any  applicable  language  binding;  see  B.l.3.3. 

POSIX.1  is  not  a  tutorial  on  the  use  of  the  specified  interface,  nor  is  this  Rationale. 
However,  the  Rationale  includes  some  references  to  well-regarded  historical  docu¬ 
mentation  on  the  UNIX  System  in  A.3. 

B.l.1.1  POSIX.1  and  the  C  Standard 

Some  C  language  functions  and  definitions  were  handled  by  POSIX.1,  but  most 
were  handled  by  the  C  Standard  {2}.  The  general  guideline  is  that  POSIX.1  | 
retained  responsibility  for  operating-system  specific  functions,  while  the  | 
C  Standard  {2}  defined  C  library  functions.  See  also  B.2.7  and  B.8. 
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There  are  several  areas  in  which  the  two  standards  differ  philosophically: 

(1)  Function  parameter  type  lists.  These  appear  in  the  syntax  of  the 
C  Standard  {2}.  In  this  version  of  POSIX.l,  the  parameter  lists  were  res¬ 
tated  in  terms  of  these  function  prototypes.  There  were  two  major  rea¬ 
sons  for  making  this  change  from  IEEE  Std  1003.1-1988:  the  use  of  the 
C  Standard  {2}  was  rapidly  becoming  more  widespread,  and  implemen¬ 
tors  were  experiencing  difficulties  with  some  of  the  function  prototypes 
where  guidance  was  not  provided  in  POSIX.l.  (The  modifier  const  pro¬ 
vided  the  most  difficulty.)  Specific  guidance  and  permission  remains  in 
POSIX.l  for  translation  to  common-usage  C. 

(2)  Single  vs.  multiple  processes.  The  C  Standard  {2}  specifies  a  language 
that  can  be  used  on  single-process  operating  systems  and  as  a  freestand¬ 
ing  base  for  the  implementation  of  operating  systems  or  other  stand¬ 
alone  programs.  However,  the  POSIX.l  interface  is  that  of  a  multiprocess 
timesharing  system.  Thus,  POSIX.l  has  to  take  multiple  processes  into 
account  in  places  where  the  C  Standard  {2}  does  not  mention  processes  at 
all,  such  as  kill().  See  also  B.l. 3.1.1. 

(3)  Single  vs.  multiple  operating  system  environments.  The  C  Standard  {2} 
specifies  a  language  that  may  be  useful  on  more  than  one  operating  sys¬ 
tem  and  thus  has  means  of  tailoring  itself  to  the  particular  current 
environment.  POSIX.l  is  an  operating  system  interface  specification  and 
thus  by  definition  is  only  concerned  with  one  operating  system  environ¬ 
ment,  even  though  it  has  been  carefully  written  to  be  broadly  implement- 
able  (see  Broadly  Implementable  in  the  Introduction)  in  terms  of  various 
underlying  operating  systems.  See  also  B.l. 3. 1.1. 

(4)  Translation  vs.  execution  environment.  POSIX.l  is  primarily  concerned 
with  the  C  Standard  {2)  execution  environment,  leaving  the  translation 
environment  to  the  C  Standard  {2}.  See  also  B.l. 3. 1.1. 

(5)  Hosted  vs.  freestanding  implementations.  All  POSIX.l  implementations 
are  hosted  in  the  sense  of  the  C  Standard  {2}.  See  also  the  remarks  on 
conformance  in  the  Introduction. 

(6)  Text  vs.  binary  file  modes.  The  C  Standard  {2}  defines  text  and  binary 
modes  for  a  file.  But  the  POSIX.1  interface  and  historical  implementa¬ 
tions  related  to  it  make  no  such  distinction,  and  all  functions  defined  by 
POSIX.l  treat  files  as  if  these  modes  were  identical.  (It  should  not  be 
stated  that  POSIX.1  files  are  either  text  or  binary.)  The  definitions  in  the 
C  Standard  {2}  were  written  so  that  this  interpretation  is  possible.  In 
particular,  text  mode  files  are  not  required  to  end  with  a  line  separator, 
which  also  means  that  they  are  not  required  to  include  a  line  separator 
at  all. 

Furthermore,  there  is  a  basic  difference  in  approach  between  the  Rationale 
accompanying  the  C  Standard  {2}  and  this  Rationale  Annex.  The  C  Standard  {2} 
Rationale,  a  separate  document,  addresses  almost  all  changes  as  differences  from 
the  Base  Documents  of  the  C  Standard  {2},  usually  either  Kernighan  and  Ritchie 
{B46}  or  the  1984  /usr/ group  Standard  {B59}.  This  Rationale  cannot  do  that, 
since  there  are  many  more  variants  of  (and  Base  Documents  for)  the  operating 
system  interface  than  for  the  C  language.  The  most  noticeable  aspect  of  this 
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119  difference  is  that  the  C  Standard  {2}  Rationale  identifies  “QUIET  CHANGES”  from  | 

120  the  Base  Documents.  This  Annex  cannot  include  such  markings,  since  a  quiet  | 

121  change  from  one  historical  implementation  may  correspond  exactly  to  another  his- 

122  torical  implementation,  and  may  be  very  noticeable  to  an  application  written  for 

123  yet  another. 

124  The  following  subclauses  justify  the  inclusion  or  omission  of  various  C  language  | 

125  functions  in  POSIX.  1  or  the  C  Standard  {2}.  | 

126  B.l. 1.1.1  Solely  by  POSIX.1 

127  These  return  parameters  from  the  operating  system  environment:  ctermidO,  \ 

128  tty  name  {),  and  isattyi). 

129  The  fileno ()  and  fdopen  ()  functions  map  between  C  language  stream  pointers  and 

130  POSIX.1  file  descriptors. 

131  B.l. 1.1.2  Solely  by  the  C  Standard  | 

132  There  are  many  functions  that  are  useful  with  the  operating  system  interface  and 

133  are  required  for  conformance  with  POSIX.1,  but  that  are  properly  part  of  the 

134  C  Language.  These  are  listed  in  8.1,  which  also  notes  which  functions  are  defined 

135  by  both  POSIX.1  and  the  C  Standard  {2}.  Certain  terms  defined  by  the  C  Standard  | 

136  {2}  are  incorporated  by  POSIX.1  in  2.7.  j 

137  Some  routines  were  considered  too  specialized  to  be  included  in  POSIX.1.  These  | 

138  include  bsearch  ( )  and  qsorti ).  | 

139  B.l. 1.1.3  By  Neither  POSIX.1  Nor  the  C  Standard  j 

140  Some  functions  were  considered  of  marginal  utility  and  problematical  when  inter- 

141  national  character  sets  were  considered:  _toupper{),  _tolower(),  toasciiO,  and 

142  isascii  (). 

143  Although  malloci)  and  free()  are  in  the  C  Standard  {2}  and  are  required  by  8.1  of 

144  POSIX.1,  neither  brk{)  nor  sbrk()  occur  in  either  standard  (although  they  were  in 

145  the  1984  /usr /group  Standard  {B59}),  because  POSIX.1  is  designed  to  provide  the 

146  basic  set  of  functions  required  to  write  a  Conforming  POSIX.1  Application;  the 

147  underlying  implementation  of  malloci )  or  free()  is  not  an  appropriate  concern  for 

148  POSIX.1. 

149  B.l. 1.1.4  Base  by  POSIX.1,  Additions  by  the  C  Standard  | 

150  Since  the  C  Standard  {2}  does  not  depend  on  POSIX.1  in  any  way,  there  are  no 

151  items  in  this  category. 

152  B.l. 1.1. 5  Base  by  the  C  Standard,  Additions  by  POSIX.1  | 

153  The  C  Standard  {2}  has  to  define  errno  if  only  because  examining  that  variable  | 

154  offers  the  only  way  to  determine  when  some  mathematics  routines  fail.  But 

155  POSIX.1  uses  it  more  extensively  and  adds  some  semantics  to  it  in  2.4,  which  also 

156  defines  some  values  for  it. 

157  Many  numerical  limits  used  by  the  C  Standard  {2}  were  incorporated  by  POSIX.1  | 

158  in  2.8,  and  some  new  ones  were  added,  all  to  be  found  in  the  header  <limit  s  .  h>. 
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159  The  C  Standard  {2}  provides  signal^ ),  a  minimal  functionality  for  interrupts.  The  | 

160  POSIX.l  definition  replaces  this  with  an  elaborate  mechanism  that  deals  with  | 

161  multiple  processes  and  is  reliable  when  signals  come  from  outside  sources. 

162  The  time ()  function  is  used  by  the  C  Standard  {2},  but  POSIX.l  further  specifies  | 

163  the  time  value. 

164  The  getenui)  function  is  referenced  in  2.6  and  3.1.2  and  is  also  defined  by  the  | 

165  C  Standard  {2}.  | 

166  The  rename  ()  function  is  extended  to  further  specify  its  behavior  when  the  new 

167  filename  already  exists  or  either  argument  refers  to  a  directory. 

168  The  setlocale ()  function  and  the  handling  of  time  zones  were  further  specified  to  | 

169  take  advantage  of  the  POSIX  environment.  | 

170  The  standard-I/O  functions  were  specified  in  terms  of  their  relationship  to  file  | 

171  descriptors  and  the  relationship  between  multiple  processes.  | 

172  B.l.  1.1.6  Related  Functions  by  Both 

173  The  C  Standard  {2}  definition  of  compliance  and  the  POSIX.l  definition  of  confor-  \ 

174  mance  are  similar,  although  the  latter  notes  certain  potential  hardware 

175  limitations. 

176  POSIX.1  defined  a  portable  filename  character  set  in  2.2.2  that  is  like  the  | 

177  C  Standard  {2}  identifier  character  set.  However,  POSIX.l  did  not  allow  upper-  | 

178  and  lowercase  characters  to  be  considered  equivalent.  See  filename  portability  in 

179  2.3.4. 

iso  The  exit ()  function  is  defined  only  by  the  C  Standard  {2}  because  it  refers  to  clos-  | 

181  ing  streams,  and  that  subject,  as  well  as  fclose ()  itself,  is  defined  almost  entirely  | 

182  by  the  C  Standard  {2}.  But  POSIX.l  defined  _exit(),  which  also  adds  semantics  to  | 

183  exit().  This  allows  POSIX.1  to  omit  references  to  the  C  Standard  {2}  atexit ()  | 

184  function. 

185  POSIX.1  defined  kill(),  while  the  C  Standard  {2}  defined  raise (),  which  is  similar  | 

186  except  that  it  does  not  have  a  process  ID  argument,  since  the  language  defined  by  | 

187  the  C  Standard  {2}  does  not  incorporate  the  idea  of  multiple  processes. 

188  The  new  functions  sigsetjmp ()  and  siglongjmpi)  were  added  to  provide  similar 

189  functions  to  the  C  Standard  {2}  setjmpi)  and  longjmpO  that  additionally  save  and  | 

190  restore  signal  state. 

191  B.1.2  Normative  References  I 

192  There  is  no  additional  rationale  provided  for  this  subclause. 
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193  B.1.3  Conformance 

194  These  conformance  definitions  are  descended  from  those  of  conforming  implemen-  \ 

195  tation,  conforming  application,  and  conforming  portable  application  of  early  | 

196  drafts,  but  were  changed  to  clarify  | 

197  (1)  Extensions,  options,  and  limits; 

198  (2)  Relations  among  the  three  terms,  and; 

199  (3)  Relations  between  POSIX.l  and  the  C  Standard  {2}. 


200  B.1.3. 1  Implementation  Conformance 

201  These  definitions  allow  application  developers  to  know  what  to  depend  on  in  an 

202  implementation. 

203  There  is  no  definition  of  a  strictly  conforming  implementation ;  that  would  be  an 

204  implementation  that  provides  only  those  facilities  specified  by  POSIX.1  with  no 

205  extensions  whatsoever.  This  is  because  no  actual  operating  system  implementa- 

206  tion  can  exist  without  system  administration  and  initialization  facilities  that  are 

207  beyond  the  scope  of  POSIX.l. 

208  B.1.3. 1.1  Requirements 

209  The  word  “support”  is  used,  rather  than  “provide,”  in  order  to  allow  an  implemen- 

210  tation  that  has  no  resident  software  development  facilities,  but  that  supports  the 

211  execution  of  a  Strictly  Conforming  POSIX.l  Application,  to  be  a  conforming  imple- 

212  mentation.  See  also  B. 1.1.1. 

213  B.1.3. 1.2  Documentation 

214  The  conforming  documentation  is  required  to  use  the  same  numbering  scheme  as 

215  POSIX.l  for  purposes  of  cross  referencing.  This  requirement  is  consistent  with 

216  and  supplements  the  verification  test  assertions  being  developed  by  other  POSIX  | 

217  groups.  All  options  that  an  implementation  chooses  shall  be  reflected  in 

218  climit s  .  h>  and  <unistd .  h>. 

219  Note  that  the  use  of  “may”  in  terms  of  where  conformance  documents  record  | 

220  where  implementations  may  vary  implies  that  it  is  not  required  to  describe  those  | 

221  features  identified  as  undefined  or  unspecified. 

222  Other  aspects  of  systems  must  be  evaluated  by  purchasers  for  suitability.  Many 

223  systems  incorporate  buffering  facilities,  maintaining  updated  data  in  volatile 

224  storage  and  transferring  such  updates  to  nonvolatile  storage  asynchronously. 

225  Various  exception  conditions,  such  as  a  power  failure  or  a  system  crash,  can  cause 

226  this  data  to  be  lost.  The  data  may  be  associated  with  a  file  that  is  still  open,  with 

227  one  that  has  been  closed,  with  a  directory,  or  with  any  other  internal  system  data 

228  structures  associated  with  permanent  storage.  This  data  can  be  lost,  in  whole  or 

229  part,  so  that  only  careful  inspection  of  file  contents  could  determine  that  an 

230  update  did  not  occur. 

231  Also,  interrelated  file  activities,  where  multiple  files  and/or  directories  are 

232  updated,  or  where  space  is  allocated  or  released  in  the  file  system  structures,  can 

233  leave  inconsistencies  in  the  relationship  between  data  in  the  various  files  and 
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directories,  or  in  the  file  system  itself.  Such  inconsistencies  can  break  applica¬ 
tions  that  expect  updates  to  occur  in  a  specific  sequence,  so  that  updates  in  one 
place  correspond  with  related  updates  in  another  place. 

For  example,  if  a  user  creates  a  file,  places  information  in  the  file,  and  then 
records  this  action  in  another  file,  a  system  or  power  failure  at  this  point  followed 
by  restart  may  result  in  a  state  in  which  the  record  of  the  action  is  permanently 
recorded,  but  the  file  created  (or  some  of  its  information)  has  been  lost.  The 
consequences  of  this  to  the  user  may  be  undesirable.  For  a  user  on  such  a  system, 
the  only  safe  action  may  be  to  require  the  system  administrator  to  have  a  policy 
that  requires,  after  any  system  or  power  failure,  that  the  entire  file  system  must 
be  restored  from  the  most  recent  backup  copy  (causing  all  intervening  work  to  be 
lost). 

The  characteristics  of  each  implementation  will  vary  in  this  respect  and  may  or 
may  not  meet  the  requirements  of  a  given  application  or  user.  Enforcement  of 
such  requirements  is  beyond  the  scope  of  POSIX.l.  It  is  up  to  the  purchaser  to 
determine  what  facilities  are  provided  in  an  implementation  that  affect  the  expo¬ 
sure  to  possible  data  or  sequence  loss  and  also  what  underlying  implementation 
techniques  and/or  facilities  are  provided  that  reduce  or  limit  such  loss  or  its 
consequences. 

B.l.3.1.3  Conforming  Implementation  Options 

Within  POSIX.1  there  are  some  symbolic  constants  that,  if  defined,  indicate  that  a 
certain  option  is  enabled.  Other  symbolic  constants  exist  in  POSIX.l  for  other  rea¬ 
sons.  This  clause  helps  clarify  which  constants  are  related  to  true  “options”  and  | 
which  are  related  more  to  the  behavior  of  differing  systems. 

To  accommodate  historical  implementations  where  there  were  distinct  semantics 
in  certain  situations,  but  where  one  was  not  clearly  better  or  worse  than  another, 
early  drafts  of  POSIX.1  permitted  either  of  (typically)  two  options  using  “may.”  At 
the  request  of  the  working  group  developing  test  assertions,  this  was  changed  to  | 
be  specified  by  formal  options  with  flags.  It  quickly  became  obvious  that  these 
would  be  treated  as  options  that  could  be  selected  by  a  purchaser,  when  the  intent 
of  the  developers  of  POSIX.1  was  to  allow  either  behavior  (or  both,  in  some  cases)  | 
to  conform  to  the  standard,  and  to  constrain  the  application  to  accommodate 
either.  Thus,  these  options  were  removed  and  the  phrase  “An  implementation 
may  either”  introduced  to  replace  the  option.  Where  this  phrase  is  used,  it  indi¬ 
cates  that  an  application  shall  tolerate  either  behavior. 

It  is  intended  that  all  conforming  applications  shall  tolerate  either  behavior  and  | 
that  only  in  the  most  exceptional  of  circumstances  (driven  by  technical  need) 
should  a  purchaser  specify  only  one  behavior.  Backwards  compatibility  is  not  con¬ 
sidered  exceptional,  as  this  is  not  consistent  with  the  intent  of  POSIX.1:  to  pro¬ 
mote  the  portability  of  applications  (and  the  development  of  portable 
applications). 

An  application  can  tolerate  these  behaviors  either  by  ignoring  the  differences  (if 
they  are  irrelevant  to  the  application)  or  by  taking  an  action  to  assure  a  known 
state.  It  might  be  that  that  action  would  be  redundant  on  some  implementations. 

Validation  programs,  which  are  applications  in  this  sense,  could  either  report  the 
actual  result  found  or  simply  ignore  the  difference.  In  no  case  should  either 
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280  acceptable  behavior  be  treated  as  an  error.  This  may  complicate  the  validation 

281  slightly,  but  is  more  consistent  with  the  intent  of  this  permissible  variation  in 

282  behavior. 

283  In  certain  circumstances,  the  behavior  may  vary  for  a  given  process.  For  exam- 

284  pie,  in  the  presence  of  networked  file  systems,  whether  or  not  dot  and  dot-dot  are 

285  present  in  the  directory  may  vary  with  the  directory  being  searched,  and  the  pro- 

286  gram  would  only  be  portable  if  it  tolerated,  but  did  not  require,  the  presence  of 

287  these  entries  in  a  directory. 

288  In  situations  like  this,  it  is  typically  easier  to  simply  ignore  dot  and  dot-dot  if  they 

289  are  found  than  to  try  to  determine  if  they  should  be  expected  or  not. 

290  B.  1.3.2  Application  Conformance 

291  These  definitions  guide  users  or  adaptors  of  applications  in  determining  on  which 

292  implementations  an  application  will  run  and  how  much  adaptation  would  be 

293  required  to  make  it  run  on  others.  These  three  definitions  are  modeled  after 

294  related  ones  in  the  C  Standard  {2}. 

295  POSIX.  1  occasionally  uses  the  expressions  portable  application  or  conforming 

296  application .  As  they  are  used,  these  are  synonyms  for  any  of  these  three  terms. 

297  The  differences  between  the  three  classes  of  application  conformance  relate  to  the 

298  requirements  for  other  standards,  or,  in  the  case  of  the  Conforming  POSIX.  1  Appli- 

299  cation  Using  Extensions,  to  implementation  extensions.  When  one  of  the  less 

300  explicit  expressions  is  used,  it  should  be  apparent  from  the  context  of  the  discus- 

301  sion  which  of  the  more  explicit  names  is  appropriate. 

302  B.l.3.2.1  Strictly  Conforming  POSIX.1  Application 

303  This  definition  is  analogous  to  that  of  a  C  Standard  {2}  conforming  program . 

304  The  major  difference  between  a  Strictly  Conforming  POSIX.1  Application  and  a 

305  C  Standard  {2}  strictly  conforming  program  is  that  the  latter  is  not  allowed  to  use 

306  features  of  POSIX.1  that  are  not  in  the  C  Standard  {2}. 

307  B.l.3.2.2  Conforming  POSIX.1  Application 

308  Examples  of  <National  Bodies>  include  ANSI,  BSI,  and  AFNOR. 

309  B.l. 3.2.3  Conforming  POSIX.1  Application  Using  Extensions 

310  Due  to  possible  requirements  for  configuration  or  implementation  characteristics 

311  in  excess  of  the  specifications  in  2.8  or  related  to  the  hardware  (such  as  array  size 

312  or  file  space),  not  every  Conforming  POSIX.1  Application  Using  Extensions  will 

313  run  on  every  conforming  implementation. 

314  B. 1.3.3  Language-Dependent  Services  for  the  C  Programming  Language 

315  POSIX.1  is,  for  historical  reasons,  both  a  specification  of  an  operating  system 

316  interface  and  a  C  binding  for  that  specification.  It  is  clear  that  these  need  to  be 

317  separated  into  unique  entities,  but  the  urgency  of  getting  the  initial  standard  out, 

318  and  the  fact  that  C  is  the  de  facto  primary  language  on  systems  similar  to  the 
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UNIX  system,  makes  this  a  necessary  and  workable  situation. 

Nevertheless,  work  will  be  done  on  language  bindings,  beyond  that  for  C  before 
the  specification  and  the  current  binding  are  separated.  Language  bindings  for 
languages  other  than  C  should  not  model  themselves  too  closely  on  the  C  binding 
and  in  the  process  pick  up  various  idiosyncrasies  of  C. 

Where  functionality  is  duplicated  in  POSIX.1  [e.g.,  open()  and  creat()]  there  is  no 
reason  for  that  duplication  to  be  carried  forward  into  another  language.  On  the 
other  hand,  some  languages  have  functionality  already  in  them  that  is  essentially 
the  same  as  that  provided  in  POSIX.1.  In  this  case,  a  mapping  between  the  func¬ 
tionality  in  that  language  and  the  underlying  functionality  in  POSIX.1  is  a  better 
choice  than  mimicking  the  C  binding. 

Since  C  has  no  syntax  for  I/O,  and  I/O  is  a  large  fraction  of  POSIX.1,  the  paradigm 
of  functions  has  been  used.  This  may  not  be  appropriate  to  another  language. 
For  example,  FORTRAN’S  REWIND  statement  is  a  candidate  to  map  onto  a  special 
case  of  Iseek  (),  and  its  SEEK  statement  may  completely  cover  for  Iseek  ().  If  this  is 
the  case,  there  is  no  reason  to  provide  SUBROUTINES  with  the  same  functionality. 

In  the  more  general  case,  file  descriptors  and  FORTRAN’S  logical  unit  numbers 
may  have  a  useful  mapping.  FORTRAN’S  ERR=  option  in  I/O  operations  might 
replace  returning  -1;  the  whole  concept  of  errors  might  be  handled  differently. 

As  was  done  with  C,  it  is  not  unreasonable  for  other  language  bindings  to  specify 
some  areas  that  are  undefined  or  unspecified  by  the  underlying  language  stan¬ 
dard  or  that  are  permissible  as  extensions.  This  may,  in  fact,  solve  some  difficult 
problems. 

Using  as  much  as  possible  of  the  target  language  in  the  binding  enhances  porta¬ 
bility.  If  a  program  wishes  to  use  some  POSIX.1  capabilities,  and  these  are  bound 
to  the  language  statements  rather  than  appearing  as  additional  procedure  or 
function  calls,  and  the  program  does  in  fact  conform  to  the  language  standard 
while  using  those  functions,  it  will  port  to  a  larger  range  of  systems  than  one  that 
is  obligated  to  use  procedure  or  function  calls  introduced  specifically  for  the  bind¬ 
ing  to  POSIX.1  to  do  the  same  thing. 

A  program  that  requires  the  POSIX.1  capabilities  that  are  not  bound  to  the  stan¬ 
dard  language  directly  (as  above)  has  no  chance  to  be  portable  outside  the  POSIX.1 
environment.  It  does  not  matter  whether  the  extension  is  syntactic  or  a  new  func¬ 
tion;  it  still  will  not  port  without  effort.  Given  this,  it  seems  unreasonable  not  to 
consider  language  extensions  when  determining  how  best  to  map  the  functionality 
of  POSIX.1  into  a  particular  language  binding.  For  example,  a  new  statement 
similar  to  READ,  which  loads  the  values  from  a  call  like  stat(),  might  be  the  best 
solution  for  reading  the  data  lists  returned  as  structures  in  C  into  a  list  of  FOR¬ 
TRAN  variables. 

No  attempt  to  mimic  printfO  or  scanfO  (or  the  rest  of  the  C  Standard  {2}  func-  | 
tions)  should  be  made;  the  equivalent  functions  in  the  language  should  be  used. 
(Formatted  READ  and  WRITE  in  FORTRAN,  read/readln  and  write/writeln 
in  Pascal,  for  example.) 

There  is  an  inherent  special  relationship  between  an  operating  system  standard 
and  a  language  standard.  It  is  unlikely  that  standards  for  other  kinds  of  features 
(such  as  graphics)  will  bind  directly  to  statements  in  a  general  purpose  language. 
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365  However,  an  operating  system  standard  should  provide  the  services  required  by  a 

366  language.  This  is  an  unusual  situation,  and  the  tendency  to  use  only  new  func- 

367  tions  and  procedures  when  creating  a  binding  should  be  examined  carefully.  (A 

368  one-to-one  binding  in  all  cases  is  probably  not  possible,  but  bindings  such  as  those 

369  for  standard  I/O  in  Section  8  may  be  possible.) 

370  Binding  directly  to  the  language,  where  possible,  should  be  encouraged  both  by 

371  making  maximal  use  of  the  mapping  between  the  operating  system  and  the 

372  language  that  naturally  exists  and,  where  appropriate,  by  having  the  languages 

373  request  changes  to  the  operating  system  to  facilitate  such  a  mapping.  (A  future 

374  inclusion  of  a  truncate  function,  specifically  for  the  FORTRAN  ENDFILE  state- 

375  ment,  but  that  is  also  generally  useful,  is  a  good  example.) 

376  Part  of  the  job  of  creating  a  binding  is  choosing  names  for  functions  that  are  intro- 

377  duced,  and  these  will  need  to  be  appropriate  for  that  language.  It  is  possible  to 

378  use  other  than  the  most  restrictive  form  of  a  name,  since,  as  discussed  previously, 

379  using  these  functions  inherently  makes  the  application  not  portable  to  systems 

380  that  are  not  POSIX.1,  and  if  POSIX.1  conformant  systems  typically  accept  names 

381  that  the  lowest-common-denominator  system  will  not,  there  is  no  reason  to  a 

382  priori  exclude  such  names.  (The  specific  example  is  C,  where  it  is  typically  “non- 

383  UNIX”  systems  that  limit  external  identifiers  to  six  characters.) 

384  See  B.1.1  for  additional  information  about  C  bindings. 

385  B.l. 3.3.1  Types  of  Conformance 

386  There  is  no  additional  rationale  provided  for  this  subclause. 

387  B.l.3.3.2  C  Standard  Language-Dependent  System  Support 

388  The  issue  of  “namespace  pollution”  needs  to  be  understood  in  this  context.  See 

389  B.2.7.2. 

390  B.l.3.3.3  Common-Usage  C  Language-Dependent  System  Support 

391  The  issue  of  “namespace  pollution”  needs  to  be  understood  in  this  context.  See 

392  B.2.7.2. 

393  B.l.3.4  Other  C  Language-Related  Specifications 

394  The  information  concerning  the  use  of  library  functions  was  adapted  from  a 

395  description  in  the  C  Standard  {2}.  Here  is  an  example  of  how  an  application  pro- 

396  gram  can  protect  itself  from  library  functions  that  may  or  may  not  be  macros, 

397  rather  than  true  functions: 

398  The  atoi()  function  may  be  used  in  any  of  several  ways: 

399  (1)  By  use  of  its  associated  header  (possibly  generating  a  macro  expansion) 

400  finclude  <stdlib.h> 

401  /*...*/ 

402  i  =  atoi(str); 

403  (2)  By  use  of  its  associated  header  (assuredly  generating  a  true  function  call) 
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tinclude  <stdlib.h> 
tundef  atoi 
/*  ...  */ 
i  =  atoi  ( str ) ; 

or 

tinclude  <stdlib.h> 

/*  ...  */ 
i  =  (atoi)  (str) ; 

(3)  By  explicit  declaration 

extern  int  atoi  (const  char  *) ; 

/*  ...  */ 
i  =  atoi  (str) ; 

(4)  By  implicit  declaration 

/*  ...  */ 
i  =  atoi ( str ) ; 

(Assuming  no  function  prototype  is  in  scope.  This  is  not  allowed  by  the  | 
C  Standard  {2}  for  functions  with  variable  arguments;  furthermore,  | 
parameter  type  conversion  “widening”  is  subject  to  different  rules  in  this 
case.) 

Note  that  the  C  Standard  {2}  reserves  names  starting  with  ' for  the  compiler. 
Therefore,  the  compiler  could,  for  example,  implement  an  intrinsic,  built-in  func¬ 
tion  _asm_builtin_atoi(),  which  it  recognized  and  expanded  into  inline  assembly 
code.  Then,  in  <stdlib  .  h>,  there  could  be  the  following: 

tdefine  atoi (X)  _asm_builtin_atoi (X) 

The  user’s  “normal”  call  to  atoi ()  would  then  be  expanded  inline,  but  the  imple¬ 
mentor  would  also  be  required  to  provide  a  callable  function  named  atoi  ()  for  use 
when  the  application  requires  it;  for  example,  if  its  address  is  to  be  stored  in  a 
function  pointer  variable. 

B.l.3.5  Other  Language-Related  Specifications  I 

It  is  intended  that  “long”  identifiers  and  multicase  linkage  would  be  supported  on  | 
POSIX.1  systems  for  all  languages,  including  C.  This  is  where  that  condition  is  | 
stated.  The  portion  of  the  sentence  about  “if  such  extensions  are”  is  included  to  | 
permit  languages  that  have  an  absolute  maximum,  or  an  absolute  requirement  of  | 
case  folding,  to  be  conformant. 

The  requirement  for  longer  names  is  included  for  several  reasons: 

(1)  Most  systems  similar  to  POSIX.1  are  already  conformant.  I 

(2)  Many  existing  language  standards  restrict  the  length  of  names  to  accom¬ 
modate  existing  systems  that  cannot  be  modified  to  allow  longer  names.  | 
However,  those  systems  are  not  expected  to  be  POSIX.1  conformant,  for  | 
other  reasons. 
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(3)  Many  historical  applications  rely  on  such  long  names. 

(4)  Future  languages  (such  as  FORTRAN  88)  are  likely  to  require  it. 

Specific  to  FORTRAN  77  {B21},  that  standard  permits  long  names,  and  this  part  of 
ISO/IEC  9945  requires  that  FORTRAN  implementations  running  on  POSIX.1  sup¬ 
port  long  names.  The  requirements  of  case  distinction  and  length  are  considered 
orthogonal,  but  both  are  required  if  both  are  permitted  by  the  language.  Note 
that  a  language  can  be  conformant  to  POSIX.1  even  though  a  binding  does  not 
exist,  because  an  application  need  not  step  outside  the  language  standard  to  write 
a  useful  program. 

This  requirement  permits  the  use  of  reasonable-length  names  in  a  POSIX.1  bind¬ 
ing  to  a  language  such  as  FORTRAN.  Clearly  nothing  prohibits  a  program  that 
does  conform  to  the  FORTRAN  minima  to  compile  and  run  on  POSIX.1. 

It  is  within  the  constraints  of  POSIX.1  to  specify  the  behavior  of  the  language  pro¬ 
cessors  and  linker,  consistent  with  the  language,  as  it  is  a  specification  for  an  exe¬ 
cution  environment.  This  is  different  than  a  package  such  as  GKS  {B27},  which 
can  reasonably  be  expected  to  be  ported  to  a  system  that  enforces  the  language 
minima. 

It  might  be  argued  that  this  specification  is  appropriate  to  the  language  binding 
committees  for  POSIX  generally,  rather  than  specifically  to  POSIX.1.  That  argu¬ 
ment  misses  the  intent.  The  intent  is  to  require  that  the  linker  and  other  code 
that  handles  “object  code”  (a  concept  not  formally  defined  in  POSIX.1)  are  able  to 
support  long  names.  This  requirement,  being  one  that  spans  all  languages, 
belongs  in  the  specification  standard,  rather  than  tied  to  any  one  language.  Note 
that  it  is  also  somewhat  permissive,  in  that  if  the  language  is  unable  to  deal  with 
long  names  it  is  permitted  not  to  require  them,  but  it  does  remove  the  argument 
that  “the  loader  might  not  permit  long  names,  so  [a  specific]  language  binding 
should  not  force  the  issue.” 

A  strictly  conforming  application  for  a  given  language  could  not  use  any  exten¬ 
sions  outside  of  POSIX.1  for  that  language  (regardless  of  the  underlying  operating 
system).  An  application  will  strictly  conform  to  POSIX.1  if  it  conforms  to  the 
language  using  additional  interfaces  from  that  language’s  binding  to  POSIX.1. 
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B.2.1  Conventions 

There  is  no  additional  rationale  provided  for  this  subclause. 
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478  B.2.2  Definitions 

479  B.2.2.1  Terminology 

480  The  meanings  specified  in  POSIX.1  for  the  words  shall,  should,  and  may  are  man- 

481  dated  by  ISO/IEC  directives.  | 

482  In  this  Rationale,  the  words  shall,  should,  and  may  are  sometimes  used  to  illus- 

483  trate  similar  usages  in  the  standard.  However,  the  Rationale  itself  does  not 

484  specify  anything  regarding  implementations  or  applications.  | 

485  conformance  document:  As  a  practical  matter,  the  conformance  document  is  | 

486  effectively  part  of  the  system  documentation.  They  are  distinguished  by  POSIX.1  | 

487  so  that  they  can  be  referred  to  distinctly.  | 

488  implementation  defined:  This  definition  is  analogous  to  that  of  the 

489  C  Standard  {2}  and,  together  with  undefined  and  unspecified,  provides  a  range  of 

490  specification  of  freedom  allowed  to  the  interface  implementor. 

491  may:  The  use  of  may  has  been  limited  as  much  as  possible,  due  both  to  confu- 

492  sion  stemming  from  its  ordinary  English  meaning  and  to  objections  regarding  the 

493  desirability  of  having  as  few  options  as  possible  and  those  as  clearly  specified  as 

494  possible. 

495  shall:  Declarative  sentences  are  sometimes  used  in  POSIX.1  as  if  they  included 

496  the  word  shall,  and  facilities  thus  specified  are  no  less  required.  For  example,  the 

497  two  statements: 

498  (1)  The  foo{)  function  shall  return  zero 

499  (2)  The  foo{ )  function  returns  zero 

500  are  meant  to  be  exactly  equivalent.  It  is  expected  that  a  future  version  of  POSIX.1  | 

501  will  be  rewritten  to  use  the  “shall”  form  more  consistently.  | 

502  should:  In  POSIX.1,  the  word  should  does  not  usually  apply  to  the  implementa- 

503  tion,  but  rather  to  the  application.  Thus,  the  important  words  regarding  imple- 

504  mentations  are  shall,  which  indicates  requirements,  and  may,  which  indicates 

505  options. 

506  obsolescent:  The  term  obsolescent  was  preferred  over  deprecated  to  represent  | 

507  functionality  that  should  not  be  used  in  new  work.  The  term  obsolescent  is  more  | 

508  intuitive  and  reduced  the  possibility  of  misunderstanding  in  the  intended  context.  | 

509  supported:  An  example  of  this  concept  is  the  setpgidi)  function.  If  the  imple- 

510  mentation  does  not  support  the  optional  job  control  feature,  it  nevertheless  has  to 

511  provide  a  function  named  setpgidi),  even  though  its  only  ability  is  that  of  return- 

512  ing  [ENOSYS]. 

513  system  documentation:  The  system  documentation  should  normally  describe  | 

514  the  whole  of  the  implementation,  including  any  extensions  provided  by  the  imple-  | 

515  mentation.  Such  documents  normally  contain  information  at  least  as  detailed  as  | 

516  the  POSIX.1  specifications.  Few  requirements  are  made  on  the  system  documen-  | 

517  tation,  but  the  term  is  needed  to  avoid  a  dangling  pointer  where  the  conformance  | 

518  document  is  permitted  to  point  to  the  system  documentation. 
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undefined:  See  implementation  defined. 
unspecified:  See  implementation  defined. 

The  definitions  for  unspecified  and  undefined  appear  nearly  identical  at  first 
examination,  but  are  not.  Unspecified  means  that  a  conforming  program  may 
deal  with  the  unspecified  behavior,  and  it  should  not  care  what  the  outcome  is. 
Undefined  says  that  a  conforming  program  should  not  do  it  because  no  definition 
is  provided  for  what  it  does  (and  implicitly  it  would  care  what  the  outcome  was  if 
it  tried  it).  It  is  important  to  remember,  however,  that  if  the  syntax  permits  the 
statement  at  all,  it  must  have  some  outcome  in  a  real  implementation. 

Thus,  the  terms  undefined  and  unspecified  apply  to  the  way  the  application 
should  think  about  the  feature.  In  terms  of  the  implementation  it  is  always 
“defined” — there  is  always  some  result,  even  if  it  is  an  error.  The  implementation 
is  free  to  choose  the  behavior  it  prefers. 

This  also  implies  that  an  implementation,  or  another  standard,  could  specify  or 
define  the  result  in  a  useful  fashion.  The  terms  apply  to  POSIX.  1  specifically. 

The  term  implementation  defined  implies  requirements  for  documentation  that 
are  not  required  for  undefined  (or  unspecified).  Where  there  is  no  need  for  a  con¬ 
forming  program  to  know  the  definition,  the  term  undefined  is  used,  even  though 
implementation  defined  could  also  have  been  used  in  this  context.  There  could  be 
a  fourth  term,  specifying  “POSIX.  1  does  not  say  what  this  does;  it  is  acceptable  to 
define  it  in  an  implementation,  but  it  does  not  need  to  be  documented,”  and 
undefined  would  then  be  used  very  rarely  for  the  few  things  for  which  any 
definition  is  not  useful. 

In  many  places  POSIX.  1  is  silent  about  the  behavior  of  some  possible  construct.  | 
For  example,  a  variable  may  be  defined  for  a  specified  range  of  values  and  | 
behaviors  are  described  for  those  values;  nothing  is  said  about  what  happens  if  | 
the  variable  has  any  other  value.  That  kind  of  silence  can  imply  an  error  in  the  | 
standard,  but  it  may  also  imply  that  the  standard  was  intentionally  silent  and  | 
that  any  behavior  is  permitted.  There  is  a  natural  tendency  to  infer  that  if  the  | 
standard  is  silent,  a  behavior  is  prohibited.  That  is  not  the  intent.  Silence  is  j 
intended  to  be  equivalent  to  the  term  unspecified.  \ 

B.2.2.2  General  Terms 

Many  of  these  definitions  are  necessarily  circular,  and  some  of  the  terms  (such  as 
process)  are  variants  of  basic  computing  science  terms  that  are  inherently  hard  to 
define.  Some  are  defined  by  context  in  the  prose  topic  descriptions  of  the  general 
concepts  in  2.3,  but  most  appear  in  the  alphabetical  glossary  format  of  the  terms  | 
in  2.2.2.  j 

Some  definitions  must  allow  extension  to  cover  terms  or  facilities  that  are  not 
explicitly  mentioned  in  POSIX.l.  For  example,  the  definition  of  file  must  permit 
interpretation  to  include  streams,  as  found  in  the  Eighth  Edition  (a  research  ver¬ 
sion  of  the  UNIX  system).  The  use  of  abstract  intermediate  terms  (such  as  object 
in  place  of,  or  in  addition  to,  file)  has  mostly  been  avoided  in  favor  of  careful 
definition  of  more  traditional  terms. 
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562  Some  terms  in  the  following  list  of  notes  do  not  appear  in  POSIX.l;  these  are 

563  marked  prefixed  with  a  asterisk  (*).  Many  of  them  have  been  specifically 

564  excluded  from  POSIX.1  because  they  concern  system  administration,  implementa- 

565  tion,  or  other  issues  that  are  not  specific  to  the  programming  interface.  Those  are 

566  marked  with  a  reason,  such  as  “implementation  defined.” 

567  appropriate  privileges:  One  of  the  fundamental  security  problems  with  many 

568  historical  UNIX  systems  has  been  that  the  privilege  mechanism  is  monolithic — a 

569  user  has  either  no  privileges  or  all  privileges.  Thus,  a  successful  “trojan  horse” 

570  attack  on  a  privileged  process  defeats  all  security  provisions.  Therefore,  POSIX.l 

571  allows  more  granular  privilege  mechanisms  to  be  defined.  For  many  historical  | 

572  implementations  of  the  UNIX  system,  the  presence  of  the  term  appropriate  \ 

573  privileges  in  POSIX.l  may  be  understood  as  a  synonym  for  super-user  (UID  0). 

574  However,  future  systems  will  undoubtedly  emerge  where  this  is  not  the  case  and 

575  each  discrete  controllable  action  will  have  appropriate  privileges  associated  with 

576  it.  Because  this  mechanism  is  implementation  defined,  it  must  be  described  in  | 

577  the  conformance  document.  Although  that  description  affects  several  parts  of  | 

578  POSIX.l  where  the  term  appropriate  privilege  is  used,  because  the  term  implemen-  | 

579  tation  defined  only  appears  here,  the  description  of  the  entire  mechanism  and  its  | 

580  effects  on  these  other  sections  belongs  in  clause  2.3  of  the  conformance  document.  | 

581  This  is  especially  convenient  for  implementations  with  a  single  mechanism  that  | 

582  applies  in  all  areas,  since  it  only  needs  to  be  described  once. 

583  clock  tick:  The  C  Standard  {2}  defines  a  similar  interval  for  use  by  the  clock  ()  | 

584  function.  There  is  no  requirement  that  these  intervals  be  the  same.  In  historical  | 

585  implementations  these  intervals  are  different.  Currently  only  the  timesi )  function  | 

586  uses  values  stated  in  terms  of  clock  ticks,  although  other  functions  might  use  | 

587  them  in  the  future.  I 

588  controlling  terminal:  The  question  of  which  of  possibly  several  special  files 

589  referring  to  the  terminal  is  meant  is  not  addressed  in  POSIX.l. 

590  | 

591  *  device  number:  The  concept  is  handled  in  stat{)  as  ID  of  device. 

592  directory:  The  format  of  the  directory  file  is  implementation  defined  and  differs 

593  radically  between  System  V  and  4.3BSD.  However,  routines  (derived  from 

594  4.3BSD)  for  accessing  directories  are  provided  in  5.1.2  and  certain  constraints  on 

595  the  format  of  the  information  returned  by  those  routines  are  made  in  5.1.1. 

596  directory  entry:  Throughout  the  document,  the  term  link  is  used  [about  the  | 

597  link ()  function,  for  example]  in  describing  the  objects  that  point  to  files  from  | 

598  directories. 

599  dot:  The  symbolic  name  dot  is  carefully  used  in  POSIX.l  to  distinguish  the  work- 

600  ing  directory  filename  from  a  period  or  a  decimal  point. 

601  dot-dot:  Historical  implementations  permit  the  use  of  these  filenames  without 

602  their  special  meanings.  Such  use  precludes  any  meaningful  use  of  these 

603  filenames  by  a  Conforming  POSIX.1  Application.  Therefore,  such  use  is  considered 

604  an  extension,  the  use  of  which  makes  an  implementation  nonconforming.  See  also 

605  B.2.3.7. 
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Epoch:  Historically,  the  origin  of  UNIX  system  time  was  referred  to  as  “00:00:00 
GMT,  January  1,  1970.”  Greenwich  Mean  Time  is  actually  not  a  term  ack¬ 
nowledged  by  the  international  standards  community;  therefore,  this  term, 
Epoch,  is  used  to  abbreviate  the  reference  to  the  actual  standard,  Coordinated 
Universal  Time.  The  concept  of  leap  seconds  is  added  for  precision;  at  the  time 
POSIX.1  was  published,  14  leap  seconds  had  been  added  since  January  1,  1970. 
These  14  seconds  are  ignored  to  provide  an  easy  and  compatible  method  of  com¬ 
puting  time  differences. 

Most  systems’  notion  of  “time”  is  that  of  a  continuously  increasing  value,  so  this 
value  should  increase  even  during  leap  seconds.  However,  not  only  do  most  sys¬ 
tems  not  keep  track  of  leap  seconds,  but  most  systems  are  probably  not  synchron¬ 
ized  to  any  standard  time  reference.  Therefore,  it  is  inappropriate  to  require  that 
a  time  represented  as  seconds  since  the  Epoch  precisely  represent  the  number  of 
seconds  between  the  referenced  time  and  the  Epoch. 

It  is  sufficient  to  require  that  applications  be  allowed  to  treat  this  time  as  if  it 
represented  the  number  of  seconds  between  the  referenced  time  and  the  Epoch.  It 
is  the  responsibility  of  the  vendor  of  the  system,  and  the  administrator  of  the  sys¬ 
tem,  to  ensure  that  this  value  represents  the  number  of  seconds  between  the 
referenced  time  and  the  Epoch  as  closely  as  necessary  for  the  application  being 
run  on  that  system. 

It  is  important  that  the  interpretation  of  time  names  and  seconds  since  the  Epoch 
values  be  consistent  across  conforming  systems.  That  is,  it  is  important  that  all 
conforming  systems  interpret  “536457599  seconds  since  the  Epoch”  as  59 
seconds,  59  minutes,  23  hours  31  December  1986,  regardless  of  the  accuracy  of 
the  system’s  idea  of  the  current  time.  The  expression  is  given  to  assure  a  con¬ 
sistent  interpretation,  not  to  attempt  to  specify  the  calendar.  The  relationship 
between  tmjyday  and  the  day  of  week,  day  of  month,  and  month  is  presumed  to 
be  specified  elsewhere  and  is  not  given  in  POSIX.1. 

Consistent  interpretation  of  seconds  since  the  Epoch  can  be  critical  to  certain 
types  of  distributed  applications  that  rely  on  such  timestamps  to  synchronize 
events.  The  accrual  of  leap  seconds  in  a  time  standard  is  not  predictable.  The 
number  of  leap  seconds  since  the  Epoch  will  likely  increase.  POSIX.1  is  more  con¬ 
cerned  about  the  synchronization  of  time  between  applications  of  astronomically 
short  duration.  These  concerns  are  expected  to  become  more  critical  in  the  future.  | 

Note  that  tmjyday  is  zero-based,  not  one-based,  so  the  day  number  in  the  exam¬ 
ple  above  is  364.  Note  also  that  the  division  is  an  integer  division  (discarding 
remainder)  as  in  the  C  language. 

Note  also  that  in  Section  8,  the  meaning  of  gmtimeO,  localtime (),  and  mktime ()  is  | 
specified  in  terms  of  this  expression.  However,  the  C  Standard  {2}  computes 
tmjyday  from  tmjnday ,  tmjnon,  and  tmjyear  in  mktime  ().  Because  it  is  stated 
as  a  (bidirectional)  relationship,  not  a  function,  and  because  the  conversion 
between  month-day-year  and  day-of-year  dates  is  presumed  well  known  and  is 
also  a  relationship,  this  is  not  a  problem. 

Note  that  the  expression  given  will  fail  after  the  year  2099.  Since  the  issue  of 
timejt  overflowing  a  32-bit  integer  occurs  well  before  that  time,  both  of  these  will 
have  to  be  addressed  in  revisions  to  POSIX.1. 
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652  FIFO  special  file:  See  pipe  in  B. 2. 2. 2. 

653  file:  It  is  permissible  for  an  implementation-defined  file  type  to  be  nonreadable 

654  or  non  writable. 

655  file  classes:  These  classes  correspond  to  the  historical  sets  of  permission  bits. 

656  The  classes  are  general  to  allow  implementations  flexibility  in  expanding  the 

657  access  mechanism  for  more  stringent  security  environments.  Note  that  a  process 

658  is  in  one  and  only  one  class,  so  there  is  no  ambiguity. 

659  filename:  At  the  present  time,  the  primary  responsibility  for  truncating 

660  filenames  containing  multibyte  characters  must  reside  with  the  application.  | 

661  Some  industry  groups  involved  in  internationalization  believe  that  in  the  future  | 

662  the  responsibility  must  reside  with  the  kernel.  For  the  moment,  a  clearer  under- 

663  standing  of  the  implications  of  making  the  kernel  responsible  for  truncation  of 

664  multibyte  file  names  is  needed. 

665  Character  level  truncation  was  not  adopted  because  there  is  no  support  in  | 

666  POSIX.l  that  advises  how  the  kernel  distinguishes  between  single  and  multibyte  | 

667  characters.  Until  that  time,  it  must  be  incumbent  upon  application  writers  to 

668  determine  where  multibyte  characters  must  be  truncated. 

669  file  system:  Historically  the  meaning  of  this  term  has  been  overloaded  with  two 

670  meanings:  that  of  the  complete  file  hierarchy  and  that  of  a  mountable  subset  of 

671  that  hierarchy;  i.e.,  a  mounted  file  system.  POSIX.l  uses  the  term  file  system  in 

672  the  second  sense,  except  that  it  is  limited  to  the  scope  of  a  process  (and  a  process’s 

673  root  directory).  This  usage  also  clarifies  the  domain  in  which  a  file  serial  number 

674  is  unique. 

675  *group  file:  Implementation  defined;  see  B.9. 

676  *historical  implementations:  This  refers  to  previously  existing  implementa- 

677  tions  of  programming  interfaces  and  operating  systems  that  are  related  to  the 

678  interface  specified  by  POSIX.1.  See  also  “Minimal  Changes  to  Historical  Imple-  | 

679  mentations”  in  the  Introduction.  | 

680  *  hosted  implementation:  This  refers  to  a  POSIX.1  implementation  that  is 

681  accomplished  through  interfaces  from  the  POSIX.l  services  to  some  alternate  form 

682  of  operating  system  kernel  services.  Note  that  the  line  between  a  hosted  imple- 

683  mentation  and  a  native  implementation  is  blurred,  since  most  implementations 

684  will  provide  some  services  directly  from  the  kernel  and  others  through  some 

685  indirect  path.  [For  example,  fopen  ()  might  use  open( );  or  mkfifoO  might  use 

686  mknod().]  There  is  no  necessary  relationship  between  the  type  of  implementation 

687  and  its  correctness,  performance,  and/or  reliability. 

688  *  implementation:  The  term  is  generally  used  instead  of  its  synonym,  system, 

689  to  emphasize  the  consequences  of  decisions  to  be  made  by  system  implementors. 

690  Perhaps  if  no  options  or  extensions  to  POSIX.l  were  allowed,  this  usage  would  not 

691  have  occurred. 

692  The  term  specific  implementation  is  sometimes  used  as  a  synonym  for  implemen¬ 
ts  tation.  This  should  not  be  interpreted  too  narrowly;  both  terms  can  represent  a 

694  relatively  broad  group  of  systems.  For  example,  a  hardware  vendor  could  market 

695  a  very  wide  selection  of  systems  that  all  used  the  same  instruction  set,  with  some 

696  systems  desktop  models  and  others  large  multiuser  minicomputers.  This  wide 
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range  would  probably  share  a  common  POSIX.  1  operating  system,  allowing  an 
application  compiled  for  one  to  be  used  on  any  of  the  others;  this  is  a  [specific] 
implementation . 

However,  that  wide  range  of  machines  probably  has  some  differences  between  the 
models.  Some  may  have  different  clock  rates,  different  file  systems,  different 
resource  limits,  different  network  connections,  etc.,  depending  on  their  sizes  or 
intended  usages.  Even  on  two  identical  machines,  the  system  administrators  may 
configure  them  differently.  Each  of  these  different  systems  is  known  by  the  term 
a  specific  instance  of  a  specific  implementation.  This  term  is  only  used  in  the  por¬ 
tions  of  POSIX.  1  dealing  with  run-time  queries:  sysconfO  and  pathconfi ). 

♦incomplete  pathname:  Absolute  pathname  has  been  adequately  defined. 

job  control:  In  order  to  understand  the  job-control  facilities  in  POSIX.  1  it  is  use¬ 
ful  to  understand  how  they  are  used  by  a  job-control-cognizant  shell  to  create  the 
user  interface  effect  of  job  control. 

While  the  job-control  facilities  supplied  by  POSIX.  1  can,  in  theory,  support  dif¬ 
ferent  types  of  interactive  job-control  interfaces  supplied  by  different  types  of 
shells,  there  is  historically  one  particular  interface  that  is  most  common  (provided 
by  BSD  C  Shell).  This  discussion  describes  that  interface  as  a  means  of  illustrat¬ 
ing  how  the  POSIX.  1  job-control  facilities  can  be  used. 

Job  control  allows  users  to  selectively  stop  (suspend)  the  execution  of  processes 
and  continue  (resume)  their  execution  at  a  later  point.  The  user  typically  employs 
this  facility  via  the  interactive  interface  jointly  supplied  by  the  terminal  I/O  driver 
and  a  command  interpreter  (shell). 

The  user  can  launch  jobs  (command  pipelines)  in  either  the  foreground  or  back¬ 
ground.  When  launched  in  the  foreground,  the  shell  waits  for  the  job  to  complete 
before  prompting  for  additional  commands.  When  launched  in  the  background, 
the  shell  does  not  wait,  but  immediately  prompts  for  new  commands. 

If  the  user  launches  a  job  in  the  foreground  and  subsequently  regrets  this,  the 
user  can  type  the  suspend  character  (typically  set  to  control-Z),  which  causes  the 
foreground  job  to  stop  and  the  shell  to  begin  prompting  for  new  commands.  The 
stopped  job  can  be  continued  by  the  user  (via  special  shell  commands)  either  as  a 
foreground  job  or  as  a  background  job.  Background  jobs  can  also  be  moved  into 
the  foreground  via  shell  commands. 

If  a  background  job  attempts  to  access  the  login  terminal  (controlling  terminal),  it 
is  stopped  by  the  terminal  driver  and  the  shell  is  notified,  which,  in  turn,  notifies 
the  user.  [Terminal  access  includes  read{)  and  certain  terminal  control  functions 
and  conditionally  includes  write().]  The  user  can  continue  the  stopped  job  in  the 
foreground,  thus  allowing  the  terminal  access  to  succeed  in  an  orderly  fashion. 
After  the  terminal  access  succeeds,  the  user  can  optionally  move  the  job  into  the 
background  via  the  suspend  character  and  shell  commands. 

Implementing  Job  Control  Shells 

The  interactive  interface  described  previously  can  be  accomplished  using  the 
POSIX.  1  job-control  facilities  in  the  following  way. 

The  key  feature  necessary  to  provide  job  control  is  a  way  to  group  processes  into 
jobs.  This  grouping  is  necessary  in  order  to  direct  signals  to  a  single  job  and  also 
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to  identify  which  job  is  in  the  foreground.  (There  is  at  most  one  job  that  is  in  the 
foreground  on  any  controlling  terminal  at  a  time.) 

The  concept  of  process  groups  is  used  to  provide  this  grouping.  The  shell  places 
each  job  in  a  separate  process  group  via  the  setpgidi)  function.  To  do  this,  the 
setpgidi)  function  is  invoked  by  the  shell  for  each  process  in  the  job.  It  is  actually 
useful  to  invoke  setpgidi )  twice  for  each  process:  once  in  the  child  process,  after 
calling  forki)  to  create  the  process,  but  before  calling  one  of  the  exec  functions  to 
begin  execution  of  the  program,  and  once  in  the  parent  shell  process,  after  calling 
fork  ()  to  create  the  child.  The  redundant  invocation  avoids  a  race  condition  by 
ensuring  that  the  child  process  is  placed  into  the  new  process  group  before  either 
the  parent  or  the  child  relies  on  this  being  the  case.  The  process  group  ID  for  the 
job  is  selected  by  the  shell  to  be  equal  to  the  process  ID  of  one  of  the  processes  in 
the  job.  Some  shells  choose  to  make  one  process  in  the  job  be  the  parent  of  the 
other  processes  in  the  job  (if  any).  Other  shells  (e.g.,  the  C  Shell)  choose  to  make 
themselves  the  parent  of  all  processes  in  the  pipeline  (job).  In  order  to  support 
this  latter  case,  the  setpgidi )  function  accepts  a  process  group  ID  parameter  since 
the  correct  process  group  ID  cannot  be  inherited  from  the  shell.  The  shell  itself  is 
considered  to  be  a  job  and  is  the  sole  process  in  its  own  process  group. 

The  shell  also  controls  which  job  is  currently  in  the  foreground.  A  foreground  and 
background  job  differ  in  two  ways:  the  shell  waits  for  a  foreground  command  to 
complete  (or  stop)  before  continuing  to  read  new  commands,  and  the  terminal  I/O 
driver  inhibits  terminal  access  by  background  jobs  (causing  the  processes  to  stop). 
Thus,  the  shell  must  work  cooperatively  with  the  terminal  I/O  driver  and  have  a 
common  understanding  of  which  job  is  currently  in  the  foreground.  It  is  the  user 
who  decides  which  command  should  be  currently  in  the  foreground,  and  the  user 
informs  the  shell  via  shell  commands.  The  shell,  in  turn,  informs  the  terminal  I/O 
driver  via  the  tcsetpgrpi)  function.  This  indicates  to  the  terminal  I/O  driver  the 
process  group  ID  of  the  foreground  process  group  (job).  When  the  current  fore¬ 
ground  job  either  stops  or  terminates,  the  shell  places  itself  in  the  foreground  via 
tcsetpgrpi)  before  prompting  for  additional  commands.  Note  that  when  a  job  is 
created  the  new  process  group  begins  as  a  background  process  group.  It  requires 
an  explicit  act  of  the  shell  via  tcsetpgrpi)  to  move  a  process  group  (job)  into  the 
foreground. 

When  a  process  in  a  job  stops  or  terminates,  its  parent  (e.g.,  the  shell)  receives 
synchronous  notification  by  calling  the  waitpidi)  function  with  the  WUNTRACED 
flag  set.  Asynchronous  notification  is  also  provided  when  the  parent  establishes  a 
signal  handler  for  SIGCHLD  and  does  not  specify  the  SA_NOCLDSTOP  flag.  Usu¬ 
ally  all  processes  in  a  job  stop  as  a  unit  since  the  terminal  I/O  driver  always  sends 
job-control  stop  signals  to  all  processes  in  the  process  group. 

To  continue  a  stopped  job,  the  shell  sends  the  SIGCONT  signal  to  the  process 
group  of  the  job.  In  addition,  if  the  job  is  being  continued  in  the  foreground,  the 
shell  invokes  tcsetpgrpi)  to  place  the  job  in  the  foreground  before  sending 
SIGCONT.  Otherwise,  the  shell  leaves  itself  in  the  foreground  and  reads  addi¬ 
tional  commands. 

There  is  additional  flexibility  in  the  POSIX.l  job-control  facilities  that  allows  devi¬ 
ations  from  the  typical  interface.  Clearing  the  TOSTOP  terminal  flag  (see  7. 1.2. 5) 
allows  background  jobs  to  perform  writei)  functions  without  stopping.  The  same 
effect  can  be  achieved  on  a  per-process  basis  by  having  a  process  set  the  signal 
action  for  SIGTTOU  to  SIGJGN. 
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Note  that  the  terms  job  and  process  group  can  be  used  interchangeably.  A  login 
session  that  is  not  using  the  job  control  facilities  can  be  thought  of  as  a  large  col¬ 
lection  of  processes  that  are  all  in  the  same  job  (process  group).  Such  a  login  ses¬ 
sion  may  have  a  partial  distinction  between  foreground  and  background 
processes;  that  is,  the  shell  may  choose  to  wait  for  some  processes  before  continu¬ 
ing  to  read  new  commands  and  may  not  wait  for  other  processes.  However,  the 
terminal  I/O  driver  will  consider  all  these  processes  to  be  in  the  foreground  since 
they  are  all  members  of  the  same  process  group. 

In  addition  to  the  basic  job-control  operations  already  mentioned,  a  job-control- 
cognizant  shell  needs  to  perform  the  following  actions: 

When  a  foreground  (not  background)  job  stops,  the  shell  must  sample  and 
remember  the  current  terminal  settings  so  that  it  can  restore  them  later  when  it 
continues  the  stopped  job  in  the  foreground  [via  the  tcgetattr()  and  tcsetattr() 
functions]. 

Because  a  shell  itself  can  be  spawned  from  a  shell,  it  must  take  special  action  to 
ensure  that  subshells  interact  well  with  their  parent  shells. 

A  subshell  can  be  spawned  to  perform  an  interactive  function  (prompting  the  ter¬ 
minal  for  commands)  or  a  noninteractive  function  (reading  commands  from  a  file). 
When  operating  noninteractively,  the  job-control  shell  will  refrain  from  perform¬ 
ing  the  job-control  specific  actions  described  above.  It  will  behave  as  a  shell  that 
does  not  support  job  control.  For  example,  all  jobs  will  be  left  in  the  same  process 
group  as  the  shell,  which  itself  remains  in  the  process  group  established  for  it  by 
its  parent.  This  allows  the  shell  and  its  children  to  be  treated  as  a  single  job  by  a 
parent  shell,  and  they  can  be  affected  as  a  unit  by  terminal  keyboard  signals. 

An  interactive  subshell  can  be  spawned  from  another  job-control-cognizant  shell 
in  either  the  foreground  or  background.  (For  example,  from  the  C  Shell,  the  user 
can  execute  the  command,  csh  &.)  Before  the  subshell  activates  job  control  by 
calling  setpgid  ()  to  place  itself  in  its  own  process  group  and  tcsetpgrpi)  to  place  its 
new  process  group  in  the  foreground,  it  needs  to  ensure  that  it  has  already  been 
placed  in  the  foreground  by  its  parent.  (Otherwise,  there  could  be  multiple  job- 
control  shells  that  simultaneously  attempt  to  control  mediation  of  the  terminal.) 
To  determine  this,  the  shell  retrieves  its  own  process  group  via  getpgrpO  and  the 
process  group  of  the  current  foreground  job  via  tcgetpgrpi).  If  these  are  not  equal, 
the  shell  sends  SIGTTIN  to  its  own  process  group,  causing  itself  to  stop.  When 
continued  later  by  its  parent,  the  shell  repeats  the  process-group  check.  When 
the  process  groups  finally  match,  the  shell  is  in  the  foreground  and  it  can  proceed 
to  take  control.  After  this  point,  the  shell  ignores  all  the  job-control  stop  signals 
so  that  it  does  not  inadvertently  stop  itself. 

Implementing  Job  Control  Applications 

Most  applications  do  not  need  to  be  aware  of  job-control  signals  and  operations; 
the  intuitively  correct  behavior  happens  by  default.  However,  sometimes  an 
application  can  inadvertently  interfere  with  normal  job-control  processing,  or  an 
application  may  choose  to  overtly  effect  job  control  in  cooperation  with  normal 
shell  procedures. 

An  application  can  inadvertently  subvert  job-control  processing  by  “blindly”  alter¬ 
ing  the  handling  of  signals.  A  common  application  error  is  to  learn  how  many 
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signals  the  system  supports  and  to  ignore  or  catch  them  all.  Such  an  application 
makes  the  assumption  that  it  does  not  know  what  this  signal  is,  but  knows  the 
right  handling  action  for  it.  The  system  may  initialize  the  handling  of  job-control 
stop  signals  so  that  they  are  being  ignored.  This  allows  shells  that  do  not  support 
job  control  to  inherit  and  propagate  these  settings  and  hence  to  be  immune  to  stop 
signals.  A  job-control  shell  will  set  the  handling  to  the  default  action  and  pro¬ 
pagate  this,  allowing  processes  to  stop.  In  doing  so,  the  job-control  shell  is  taking 
responsibility  for  restarting  the  stopped  applications.  If  an  application  wishes  to 
catch  the  stop  signals  itself,  it  should  first  determine  their  inherited  handling 
states.  If  a  stop  signal  is  being  ignored,  the  application  should  continue  to  ignore 
it.  This  is  directly  analogous  to  the  recommended  handling  of  SIGINT  described  in 
the  UNIX  Programmer’s  Manual  {B41}. 

If  an  application  is  reading  the  terminal  and  has  disabled  the  interpretation  of 
special  characters  (by  clearing  the  ISIG  flag),  the  terminal  I/O  driver  will  not  send 
SIGTSTP  when  the  suspend  character  is  typed.  Such  an  application  can  simulate 
the  effect  of  the  suspend  character  by  recognizing  it  and  sending  SIGTSTP  to  its 
process  group  as  the  terminal  driver  would  have  done.  Note  that  the  signal  is 
sent  to  the  process  group,  not  just  to  the  application  itself;  this  ensures  that  other 
processes  in  the  job  also  stop.  (Note  also  that  other  processes  in  the  job  could  be 
children,  siblings,  or  even  ancestors.)  Applications  should  not  assume  that  the 
suspend  character  is  control-Z  (or  any  particular  value);  they  should  retrieve  the 
current  setting  at  startup. 

Implementing  Job  Control  Systems 

The  intent  in  adding  4.2BSD-style  job  control  functionality  was  to  adopt  the  neces¬ 
sary  4.2BSD  programmatic  interface  with  only  minimal  changes  to  resolve  syntac¬ 
tic  or  semantic  conflicts  with  System  V  or  to  close  recognized  security  holes.  The 
goal  was  to  maximize  the  ease  of  providing  both  conforming  implementations  and 
Conforming  POSIX.l  Applications. 

Discussions  of  the  changes  can  be  found  in  the  clauses  that  discuss  the  specific  | 
interfaces.  See  B.3.2.1,  B.3.2.2,  B.3.3.1.1,  B.3.3.2,  B.3.3.4,  B.4.3.1,  B.4.3.3, 
B.7.1.1.4,  and  B.7.2.4. 

It  is  only  useful  for  a  process  to  be  affected  by  job-control  signals  if  it  is  the  des¬ 
cendant  of  a  job-control  shell.  Otherwise,  there  will  be  nothing  that  continues  the 
stopped  process.  Because  a  job-control  shell  is  allowed,  but  not  required,  by 
POSIX.1,  an  implementation  must  provide  a  mechanism  that  shields  processes 
from  job-control  signals  when  there  is  no  job-control  shell.  The  usual  method  is 
for  the  system  initialization  process  (typically  called  init),  which  is  the  ancestor 
of  all  processes,  to  launch  its  children  with  the  signal  handling  action  set  to 
SIG_IGN  for  the  signals  SIGTSTP,  SIGTTIN,  and  SIGTTOU.  Thus,  all  login  shells 
start  with  these  signals  ignored.  If  the  shell  is  not  job-control  cognizant,  then  it 
should  not  alter  this  setting  and  all  its  descendants  should  inherit  the  same 
ignored  settings.  At  the  point  where  a  job-control  shell  is  launched,  it  resets  the 
signal  handling  action  for  these  signals  to  be  SIG_DFL  for  its  children  and  (by 
inheritance)  their  descendants.  Also,  shells  that  are  not  job-control  cognizant  will 
not  alter  the  process  group  of  their  descendants  or  of  their  controlling  terminal; 
this  has  the  effect  of  making  all  processes  be  in  the  foreground  (assuming  the 
shell  is  in  the  foreground).  While  this  approach  is  valid,  POSIX.l  added  the  con¬ 
cept  of  orphaned  process  groups  to  provide  a  more  robust  solution  to  this  problem. 


B.2  Definitions  and  General  Requirements 


205 


885 

886 

887 

888 

889 

890 

891 

892 

893 

894 

895 

896 

897 

898 

899 

900 

901 

902 

903 

904 

905 

906 

907 

908 

909 

910 

911 

912 

913 

914 

915 

916 

917 

918 

919 

920 

921 

922 

923 

924 

925 

926 

927 

928 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


INFORMATION  TECHNOLOGY— PO SIX 


All  processes  in  a  session  managed  by  a  shell  that  is  not  job-control  cognizant  are 
in  an  orphaned  process  group  and  are  protected  from  stopping. 

POSIX.1  does  not  specify  how  controlling  terminal  access  is  affected  by  a  user  log¬ 
ging  out  (that  is,  by  a  controlling  process  terminating).  4.2BSD  uses  the 
v hangup  ( )  function  to  prevent  any  access  to  the  controlling  terminal  through  file 
descriptors  opened  prior  to  logout.  System  V  does  not  prevent  controlling  termi¬ 
nal  access  through  file  descriptors  opened  prior  to  logout  (except  for  the  case  of 
the  special  file,  /dev/tty).  Some  implementations  choose  to  make  processes 
immune  from  job  control  after  logout  (that  is,  such  processes  are  always  treated 
as  if  in  the  foreground);  other  implementations  continue  to  enforce 
foreground/background  checks  after  logout.  Therefore,  a  Conforming  POSIX.1 
Application  should  not  attempt  to  access  the  controlling  terminal  after  logout 
since  such  access  is  unreliable.  If  an  implementation  chooses  to  deny  access  to  a 
controlling  terminal  after  its  controlling  process  exits,  POSIX.1  requires  a  certain 
type  of  behavior  (see  7. 1.1.3). 

♦kernel:  See  system  call . 

♦library  routine:  See  system  call . 

♦logical  device:  Implementation  defined. 

♦mount  point:  The  directory  on  which  a  mounted  file  system  is  mounted.  This 
term,  like  mount ()  and  umount (),  was  not  included  because  it  was  implementa¬ 
tion  defined. 

♦mounted  file  system:  See  file  system. 

♦native  implementation:  This  refers  to  an  implementation  of  POSIX.1  that 
interfaces  directly  to  an  operating-system  kernel.  See  also  hosted  implementation 
and  cooperating  implementation.  A  similar  concept  is  a  native  UNIX  system, 
which  would  be  a  kernel  derived  from  one  of  the  original  UNIX  system  products. 

open  file  description:  An  open  file  description,  as  it  is  currently  named, 
describes  how  a  file  is  being  accessed.  What  is  currently  called  a  file  descriptor  is 
actually  just  an  identifier  or  “handle”;  it  does  not  actually  describe  anything. 

The  following  alternate  names  were  discussed: 

For  open  file  description: 

open  instance,  file  access  description,  open  file  information,  and  file 
access  information. 

For  file  descriptor: 

file  handle,  file  number  [c.fi,  filenoi)].  Some  historical  implementations 
use  the  term  file  table  entry . 

orphaned  process  group:  Historical  implementations  have  a  concept  of  an 
orphaned  process,  which  is  a  process  whose  parent  process  has  exited.  When  job 
control  is  in  use,  it  is  necessary  to  prevent  processes  from  being  stopped  in 
response  to  interactions  with  the  terminal  after  they  no  longer  are  controlled  by  a 
job-control-cognizant  program.  Because  signals  generated  by  the  terminal  are 
sent  to  a  process  group  and  not  to  individual  processes,  and  because  a  signal  may 
be  provoked  by  a  process  that  is  not  orphaned,  but  sent  to  another  process  that  is 
orphaned,  it  is  necessary  to  define  an  orphaned  process  group.  The  definition 
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assumes  that  a  process  group  will  be  manipulated  as  a  group  and  that  the  job- 
control-cognizant  process  controlling  the  group  is  outside  of  the  group  and  is  the 
parent  of  at  least  one  process  in  the  group  [so  that  state  changes  may  be  reported 
via  waitpid{) ].  Therefore,  a  group  is  considered  to  be  controlled  as  long  as  at  least 
one  process  in  the  group  has  a  parent  that  is  outside  of  the  process  group,  but 
within  the  session. 

This  definition  of  orphaned  process  groups  ensures  that  a  session  leader’s  process 
group  is  always  considered  to  be  orphaned,  and  thus  it  is  prevented  from  stopping 
in  response  to  terminal  signals. 

*passwd  file:  Implementation  defined;  see  B.9. 

parent  directory:  There  may  be  more  than  one  directory  entry  pointing  to  a 
given  directory  in  some  implementations.  The  wording  here  identifies  that 
exactly  one  of  those  is  the  parent  directory.  In  2.3.6,  dot-dot  is  identified  as  the 
way  that  the  unique  directory  is  identified.  (That  is,  the  parent  directory  is  the 
one  to  which  dot-dot  points.)  In  the  case  of  a  remote  file  system,  if  the  same  file 
system  is  mounted  several  times,  it  would  appear  as  if  they  were  distinct  file  sys¬ 
tems  (with  interesting  synchronization  properties). 

pipe:  It  proved  convenient  to  define  a  pipe  as  a  special  case  of  a  FIFO  even 
though  historically  the  latter  was  not  introduced  until  System  III  and  does  not 
exist  at  all  in  4.3BSD. 

portable  filename  character  set:  The  encoding  of  this  character  set  is  not 
specified — specifically,  ASCII  is  not  required.  But  the  implementation  must  pro¬ 
vide  a  unique  character  code  for  each  of  the  printable  graphics  specified  by 
POSIX.1.  See  also  B.2.3.5. 

Situations  where  characters  beyond  the  portable  filename  character  set  (or  histor¬ 
ically  ASCII  or  ISO/IEC  646  {!})  would  be  used  (in  a  context  where  the  portable 
filename  character  set  or  ISO/IEC  646  {1}  is  required  by  POSIX.1)  are  expected  to 
be  common.  Although  such  a  situation  renders  the  use  technically  noncompliant, 
mutual  agreement  among  the  users  of  an  extended  character  set  will  make  such 
use  portable  between  those  users.  Such  a  mutual  agreement  could  be  formalized 
as  an  optional  extension  to  POSIX.1.  (Making  it  required  would  eliminate  too 
many  possible  systems,  as  even  those  systems  using  ISO/IEC  646  {1}  as  a  base 
character  set  extend  their  character  sets  for  Western  Europe  and  the  rest  of  the 
world  in  different  ways.) 

Nothing  in  POSIX.1  is  intended  to  preclude  the  use  of  extended  characters  where 
interchange  is  not  required  or  where  mutual  agreement  is  obtained.  It  has  been 
suggested  that  in  several  places  “should”  be  used  instead  of  “shall.”  Because  (in 
the  worst  case)  use  of  any  character  beyond  the  portable  filename  character  set 
would  render  the  program  or  data  not  portable  to  all  possible  systems,  no  exten¬ 
sions  are  permitted  in  this  context. 

regular  file:  POSIX.1  does  not  intend  to  preclude  the  addition  of  structuring 
data  (e.g.,  record  lengths)  in  the  file,  as  long  as  such  data  is  not  visible  to  an 
application  that  uses  the  features  described  in  POSIX.1. 

root  directory:  This  definition  permits  the  operation  of  chrooti),  even  though 
that  function  is  not  in  POSIX.1.  See  also  file  hierarchy. 
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974  *root  file  system:  Implementation  defined. 

975  *root  of  a  file  system:  Implementation  defined.  See  mount  point . 

976  seconds  since  the  Epoch:  The  formula  here  is  not  precisely  correct  for  leap  | 

977  centuries.  See  the  discussion  for  Epoch  for  further  details.  | 

978  signal:  The  definition  implies  a  double  meaning  for  the  term.  Although  a  signal 

979  is  an  event,  common  usage  implies  that  a  signal  is  an  identifier  of  the  class  of 

980  event. 

981  *  system  call:  The  distinction  between  a  system  call  and  a  library  routine  is  an 

982  implementation  detail  that  may  differ  between  implementations  and  has  thus 

983  been  excluded  from  POSIX.l.  See  “Interface,  Not  Implementation”  in  the  Intro- 

984  duction. 

985  *  super-user:  This  concept,  with  great  historical  significance  to  UNIX  system 

986  users,  has  been  replaced  with  the  notion  of  appropriate  privileges. 

987  B.2.2.3  Abbreviations  | 

988  There  is  no  additional  rationale  provided  for  this  subclause.  | 

989  B.2.3  General  Concepts 

990  B.2.3. 1  extended  security  controls:  Allowing  an  implementation  to  define 

991  extended  security  controls  enables  the  use  of  POSIX.1  in  environments  that 

992  require  different  or  more  rigorous  security  than  that  provided  in  POSIX.l.  Exten- 

993  sions  are  allowed  in  two  areas:  privilege  and  file  access  permissions.  The  seman- 

994  tics  of  these  areas  have  been  defined  to  permit  extensions  with  reasonable,  but 

995  not  exact,  compatibility  with  all  existing  practices.  For  example,  the  elimination 

996  of  the  super-user  definition  precludes  identifying  a  process  as  privileged  or  not  by 

997  virtue  of  its  effective  user  ID. 

998  B.2.3.2  file  access  permissions:  A  process  should  not  try  to  anticipate  the 

999  result  of  an  attempt  to  access  data  by  a  priori  use  of  these  rules.  Rather,  it  should 

1000  make  the  attempt  to  access  data  and  examine  the  return  value  (and  possibly 

1001  errno  as  well),  or  use  access ().  An  implementation  may  include  other  security 

1002  mechanisms  in  addition  to  those  specified  in  POSIX.l,  and  an  access  attempt  may 

1003  fail  because  of  those  additional  mechanisms,  even  though  it  would  succeed  accord- 

1004  ing  to  the  rules  given  in  this  subclause.  (For  example,  the  user’s  security  level  | 

1005  might  be  lower  than  that  of  the  object  of  the  access  attempt.)  The  optional  supple- 

1006  mentary  group  IDs  provide  another  reason  for  a  process  to  not  attempt  to  antici- 

1007  pate  the  result  of  an  access  attempt. 

loos  B.2.3.3  file  hierarchy:  Though  the  file  hierarchy  is  commonly  regarded  to  be  a 

1009  tree,  POSIX.1  does  not  define  it  as  such  for  three  reasons: 

1010  (1)  Links  may  join  branches. 

ion  (2)  In  some  network  implementations,  there  may  be  no  single  absolute  root 
1012  directory.  See  pathname  resolution . 


208 


B  Rationale  and  Notes 


1013 

1014 

1015 

1016 

1017 

1018 

1019 

1020 
1021 
1022 

1023 

1024 

1025 

1026 

1027 

1028 

1029 

1030 

1031 

1032 

1033 

1034 

1035 

1036 

1037 

1038 

1039 

1040 

1041 

1042 

1043 

1044 

1045 

1046 

1047 

1048 

1049 

1050 

1051 

1052 

1053 


ISO/IEC  9945-1:  1990 

Part  1:  SYSTEM  API  [C  LANGUAGE]  IEEE  Std  1003.1-1990 

(3)  With  symbolic  links  (found  in  4.3BSD),  the  file  system  need  not  be  a  tree 
or  even  a  directed  acyclic  graph. 

B.2.3.4  file  permissions:  Examples  of  implementation-defined  constraints  that 
may  deny  access  are  mandatory  labels  and  access  control  lists. 

B.2.3.5  filename  portability:  Historically,  certain  filenames  have  been 
reserved.  This  list  includes  core,  /etc/passwd,  etc.  Portable  applications 
should  avoid  these. 

Most  historical  implementations  prohibit  case  folding  in  filenames;  i.e.,  treating  | 
upper-  and  lowercase  alphabetic  characters  as  identical.  However,  some  consider 
case  folding  desirable: 

—  For  user  convenience 

—  For  ease  of  implementation  of  the  POSIX.l  interface  as  a  hosted  system  on 
some  popular  operating  systems,  which  is  compatible  with  the  goal  of  mak¬ 
ing  the  POSIX.l  interface  broadly  implementable  (see  “Broadly  Implement- 
able”  in  the  Introduction) 

Variants  such  as  maintaining  case  distinctions  in  filenames,  but  ignoring  them  in 
comparisons,  have  been  suggested.  Methods  of  allowing  escaped  characters  of  the 
case  opposite  the  default  have  been  proposed 

Many  reasons  have  been  expressed  for  not  allowing  case  folding,  including: 

(1)  No  solid  evidence  has  been  produced  as  to  whether  case  sensitivity  or 
case  insensitivity  is  more  convenient  for  users. 

(2)  Making  case  insensitivity  a  POSIX.1  implementation  option  would  be 
worse  than  either  having  it  or  not  having  it,  because 

(a)  More  confusion  would  be  caused  among  users. 

(b)  Application  developers  would  have  to  account  for  both  cases  in  their 
code. 

(c)  POSIX.l  implementors  would  still  have  other  problems  with  native 
file  systems,  such  as  short  or  otherwise  constrained  filenames  or 
pathnames,  and  the  lack  of  hierarchical  directory  structure. 

(3)  Case  folding  is  not  easily  defined  in  many  European  languages,  both 
because  many  of  them  use  characters  outside  the  USASCII  alphabetic  set, 
and  because 

(a)  In  Spanish,  the  digraph  11  is  considered  to  be  a  single  letter,  the 
capitalized  form  of  which  may  be  either  LI  or  ll,  depending  on  con¬ 
text. 

(b)  In  French,  the  capitalized  form  of  a  letter  with  an  accent  may  or 
may  not  retain  the  accent  depending  on  the  country  in  which  it  is 
written. 

(c)  In  German,  the  sharp  ess  may  be  represented  as  a  single  character 
resembling  a  Greek  beta  (p)  in  lowercase,  but  as  the  digraph  ss  in 
uppercase. 
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(d)  In  Greek,  there  are  several  lowercase  forms  of  some  letters;  the  one 
to  use  depends  on  its  position  in  the  word.  Arabic  has  similar  rules. 

(4)  Many  East  Asian  languages,  including  Japanese,  Chinese,  and  Korean, 
do  not  distinguish  case  and  are  sometimes  encoded  in  character  sets  that 
use  more  than  one  byte  per  character. 

(5)  Multiple  character  codes  may  be  used  on  the  same  machine  simultane¬ 
ously.  There  are  several  ISO  character  sets  for  European  alphabets.  In 
Japan,  several  Japanese  character  codes  are  commonly  used  together, 
sometimes  even  in  filenames;  this  is  evidently  also  the  case  in  China.  To 
handle  case  insensitivity,  the  kernel  would  have  to  at  least  be  able  to  dis¬ 
tinguish  for  which  character  sets  the  concept  made  sense. 

(6)  The  file  system  implementation  historically  deals  only  with  bytes,  not 
with  characters,  except  for  slash  and  the  null  byte. 

(7)  The  purpose  of  POSIX.l  is  to  standardize  the  common,  existing  definition 
(see  “Application  Oriented”  in  the  Introduction)  of  the  UNIX  system  pro¬ 
gramming  interface,  not  to  change  it.  Mandating  case  insensitivity 
would  make  all  historical  implementations  nonstandard. 

(8)  Not  only  the  interface,  but  also  application  programs  would  need  to 
change,  counter  to  the  purpose  of  having  minimal  changes  to  existing 
application  code. 

(9)  At  least  one  of  the  original  developers  of  the  UNIX  system  has  expressed 
objection  in  the  strongest  terms  to  either  requiring  case  insensitivity  or 
making  it  an  option,  mostly  on  the  basis  that  POSIX.  1  should  not  hinder 
portability  of  application  programs  across  related  implementations  in 
order  to  allow  compatibility  with  unrelated  operating  systems. 

Two  proposals  were  entertained  regarding  case  folding  in  filenames: 

—  Remove  all  wording  that  previously  permitted  case  folding. 

Rationale:  Case  folding  is  inconsistent  with  portable  filename  character  set 
definition  and  filename  definition  (all  characters  except  slash  and  null).  No 
known  implementations  allowing  all  characters  except  slash  and  null  also 
do  case  folding. 

—  Change  “though  this  practice  is  not  recommended:”  to  “although  this  prac¬ 
tice  is  strongly  discouraged.” 

Rationale:  If  case  folding  must  be  included  in  POSIX.l,  the  wording  should 
be  stronger  to  discourage  the  practice. 

The  consensus  selected  the  first  proposal.  Otherwise,  a  portable  application  | 
would  have  to  assume  that  case  folding  would  occur  when  it  was  not  wanted,  but 
that  it  would  not  occur  when  it  was  wanted. 

B.2.3.6  file  times  update:  This  subclause  reflects  the  actions  of  historical  | 
implementations.  The  times  are  not  updated  immediately,  but  are  only  marked 
for  update  by  the  functions.  An  implementation  may  update  these  times 
immediately. 
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The  accuracy  of  the  time  update  values  is  intentionally  left  unspecified  so  that 
systems  can  control  the  bandwidth  of  a  possible  covert  channel. 

The  wording  was  carefully  chosen  to  make  it  clear  that  there  is  no  requirement 
that  the  conformance  document  contain  information  that  might  incidentally  affect 
file  update  times.  Any  function  that  performs  pathname  resolution  might  update 
several  st_atime  fields.  Functions  such  as  getpwnam  ()  and  getgrnam  ()  might 
update  the  stjatime  field  of  some  specific  file  or  files.  It  is  intended  that  these  are 
not  required  to  be  documented  in  the  conformance  document,  but  they  should 
appear  in  the  system  documentation. 

B.2.3.7  pathname  resolution:  What  the  filename  dot-dot  refers  to  relative  to 
the  root  directory  is  implementation  defined.  In  Version  7  it  refers  to  the  root 
directory  itself;  this  is  the  behavior  mentioned  in  the  standard.  In  some 
networked  systems  the  construction  / .  .  /hostname/  is  used  to  refer  to  the  root 
directory  of  another  host,  and  POSIX.l  permits  this  behavior. 

Other  networked  systems  use  the  construct  //hostname  for  the  same  purpose; 
i.e.,  a  double  initial  slash  is  used.  There  is  a  potential  problem  with  existing 
applications  that  create  full  pathnames  by  taking  a  trunk  and  a  relative  path¬ 
name  and  making  them  into  a  single  string  separated  by  /,  because  they  can 
accidentally  create  networked  pathnames  when  the  trunk  is  /.  This  practice  is 
not  prohibited  because  such  applications  can  be  made  to  conform  by  simply 
changing  to  use  /  /  as  a  separator  instead  of  / : 

(1)  If  the  trunk  is  /,  the  full  path  name  will  begin  with  III  (the  initial  /  and 
the  separator  //).  This  is  the  same  as  /,  which  is  what  is  desired.  (This 
is  the  general  case  of  making  a  relative  pathname  into  an  absolute  one  by 
prefixing  with  /  //  instead  of  /.) 

(2)  If  the  trunk  is  /A,  the  result  is  /All .  .  . ;  since  nonleading  sequences  of 
two  or  more  slashes  are  treated  as  a  single  slash,  this  is  equivalent  to  the 
desired  /  A/  ... . 

(3)  If  the  trunk  is  //A,  the  implementation-defined  semantics  will  apply. 
(The  multiple  slash  rule  would  apply.) 

Application  developers  should  avoid  generating  pathnames  that  start  with  “//”. 
Implementations  are  strongly  encouraged  to  avoid  using  this  special  interpreta¬ 
tion  since  a  number  of  applications  currently  do  not  follow  this  practice  and  may 
inadvertently  generate  “//...”. 

The  term  root  directory  is  only  defined  in  POSIX.1  relative  to  the  process.  In  some 
implementations,  there  may  be  no  absolute  root  directory.  The  initialization  of 
the  root  directory  of  a  process  is  implementation  defined. 


B.2.4  Error  Numbers 

The  definition  of  errno  in  POSIX.l  is  stricter  than  that  in  the  C  Standard  {2}.  The  | 
C  Standard  {2}  merely  requires  that  it  be  an  assignable  lvalue.  The  POSIX.l 
extern  int  errno  meets  that  requirement  and  supports  historical  usage  as  well. 
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Checking  the  value  of  errno  alone  is  not  sufficient  to  determine  the  existence  or 
type  of  an  error,  since  it  is  not  required  that  a  successful  function  call  clear  errno. 
The  variable  errno  should  only  be  examined  when  the  return  value  of  a  function 
indicates  that  the  value  of  errno  is  meaningful.  In  that  case,  the  function  is 
required  to  set  the  variable  to  something  other  than  zero. 

A  successful  function  call  may  set  the  value  of  errno  to  zero,  or  to  any  other  value 
(except  where  specifically  prohibited;  see  B.5.4.1).  But  it  is  meaningless  to  do  so, 
since  the  value  of  errno  is  undefined  except  when  the  description  of  a  function 
explicitly  states  that  it  is  set,  and  no  function  description  states  that  it  should  be 
set  on  a  successful  call.  Most  functions  in  most  implementations  do  not  change 
errno  on  successful  completion.  Exceptions  are  isatty ()  and  ptrace ().  The  latter  is 
not  in  POSIX.  1,  but  is  widely  implemented  and  clears  errno  when  called.  The 
value  of  errno  is  not  defined  unless  all  signal  handlers  that  use  functions  that 
could  change  errno  save  and  restore  it. 

POSIX.  1  requires  (in  the  Errors  subclauses  of  function  descriptions)  certain  error  | 
values  to  be  set  in  certain  conditions  because  many  existing  applications  depend  | 
on  them.  Some  error  numbers,  such  as  [EFAULT],  are  entirely  implementation 
defined  and  are  noted  as  such  in  their  description  in  2.4.  This  subclause  other-  | 
wise  allows  wide  latitude  to  the  implementation  in  handling  error  reporting.  | 

Some  of  the  Errors  clauses  in  POSIX.  1  have  two  subclauses.  The  first:  | 

“If  any  of  the  following  conditions  occur,  the  foo{ )  function  shall 
return  -1  and  set  errno  to  the  corresponding  value:” 

could  be  called  the  “mandatory”  subclause.  The  second:  | 

“For  each  of  the  following  conditions,  when  the  condition  is  detected, 
the  foo{)  function  shall  return  -1  and  set  errno  to  the  corresponding 
value:” 

could  be  informally  known  as  the  “optional”  subclause.  This  latter  subclause  has  1 
evolved  in  meaning  over  time.  In  early  drafts,  it  was  only  used  for  error  condi-  | 
tions  that  could  not  be  detected  by  certain  hardware  configurations,  such  as  the 
[EFAULT]  error,  as  described  below.  The  subclause  recently  has  also  added  condi-  | 
tions  associated  with  optional  system  behavior,  such  as  job  control  errors.  | 
Attempting  to  infer  the  quality  of  an  implementation  based  on  whether  it  detects  | 
such  conditions  is  not  useful.  | 

Following  each  one- word  symbolic  name  for  an  error,  there  is  a  one-line  tag, 
which  is  followed  by  a  description  of  the  error.  The  one-line  tag  is  merely  a 
mnemonic  or  historical  referent  and  is  not  part  of  the  specification  of  the  error. 
Many  programs  print  these  tags  on  the  standard  error  stream  [often  by  using  the 
C  Standard  {2}  perror( )  function]  when  the  corresponding  errors  are  detected,  but 
POSIX.  1  does  not  require  this  action. 

[EFAULT]  Most  historical  implementations  do  not  catch  an  error  and  set 
errno  when  an  invalid  address  is  given  to  the  functions  wait{), 
time (),  or  times().  Some  implementations  cannot  reliably  detect 
an  invalid  address.  And  most  systems  that  detect  invalid 
addresses  will  do  so  only  for  a  system  call,  not  for  a  library 
routine. 
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[EINTR] 


[ENOMEM] 

[ENOTTY] 


[EPIPE] 

[EROFS] 


POSIX.l  prohibits  conforming  implementations  from  restarting 
interrupted  system  calls.  However,  it  does  not  require  that 
[EINTR]  be  returned  when  another  legitimate  value  may  be 
substituted;  e.g.,  a  partial  transfer  count  when  read()  or  write () 
are  interrupted.  This  is  only  given  when  the  signal  catching 
function  returns  normally  as  opposed  to  returns  by  mechanisms 
like  longjmpO  or  siglongjmpi). 

The  term  main  memory  is  not  used  in  POSIX.l  because  it  is 
implementation  defined. 

The  symbolic  name  for  this  error  is  derived  from  a  time  when 
device  control  was  done  by  ioctl{)  and  that  operation  was  only 
permitted  on  a  terminal  interface.  The  term  “TTY”  is  derived 
from  teletypewriter,  the  devices  to  which  this  error  originally 
applied. 

This  condition  normally  generates  the  signal  SIGPIPE;  the  error 
is  returned  if  the  signal  does  not  terminate  the  process. 

In  historical  implementations,  attempting  to  unlinki)  or 
rmdir ()  a  mount  point  would  generate  an  [EBUSY]  error.  An 
implementation  could  be  envisioned  where  such  an  operation 
could  be  performed  without  error.  In  this  case,  if  either  the 
directory  entry  or  the  actual  data  structures  reside  on  a  read¬ 
only  file  system,  [EROFS]  is  the  appropriate  error  to  generate. 
(For  example,  changing  the  link  count  of  a  file  on  a  read-only 
file  system  could  not  be  done,  as  is  required  by  unlinki),  and 
thus  an  error  should  be  reported.) 


Two  error  numbers,  [EDOM]  and  [ERANGE],  were  added  to  this  subclause  pri¬ 
marily  for  consistency  with  the  C  Standard  {2}. 


B.2.5  Primitive  System  Data  Types 

The  requirement  that  additional  types  defined  in  this  subclause  end  in  “_t”  was 
prompted  by  the  problem  of  namespace  pollution  (see  B.2.7.2).  It  is  difficult  to 
define  a  type  (where  that  type  is  not  one  defined  by  POSIX.1)  in  one  header  file 
and  use  it  in  another  without  adding  symbols  to  the  namespace  of  the  program. 
To  allow  implementors  to  provide  their  own  types,  all  POSIX.1  conforming  applica¬ 
tions  are  required  to  avoid  symbols  ending  in  “_t”,  which  permits  the  implementor 
to  provide  additional  types.  Because  a  major  use  of  types  is  in  the  definition  of 
structure  members,  which  can  (and  in  many  cases  must)  be  added  to  the  struc¬ 
tures  defined  in  POSIX.1,  the  need  for  additional  types  is  compelling. 

The  types  such  as  ushort  and  ulong,  which  are  in  common  usage,  are  not  defined 
in  POSIX.1  (although  ushort _t  would  be  permitted  as  an  extension).  They  can  be 
added  to  <sys/types  .h>  using  a  feature  test  macro  (see  2.7.2).  A  suggested 
symbol  for  these  is  _SYSIII.  Similarly,  the  types  like  u_short  would  probably  be 
best  controlled  by  _BSD. 

Some  of  these  symbols  may  appear  in  other  headers;  see  2.7. 
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devjt  This  type  may  be  made  large  enough  to  accommodate  host- 

locality  considerations  of  networked  systems. 

This  type  must  be  arithmetic.  Earlier  drafts  allowed  this  to  be 
nonarithmetic  (such  as  a  structure)  and  provided  a  samefde () 
function  for  comparison. 

gid_t  Some  implementations  had  separated  gidj  from  uidjt  before 

POSIX.l  was  completed.  It  would  be  difficult  for  them  to 
coalesce  them  when  it  was  unnecessary.  Additionally,  it  is 
quite  possible  that  user  IDs  might  be  different  than  group  IDs 
because  the  user  ID  might  wish  to  span  a  heterogeneous  net¬ 
work,  where  the  group  ID  might  not. 

For  current  implementations,  the  cost  of  having  a  separate 
gid_t  will  be  only  lexical. 

modejt  This  type  was  chosen  so  that  implementations  could  choose  the 

appropriate  integral  type,  and  for  compatibility  with  the 
C  Standard  {2}.  4.3BSD  uses  unsigned  short  and  the  SVID  uses 
ushort,  which  is  the  same.  Historically,  only  the  low-order  six¬ 
teen  bits  are  significant. 

nlinkjt  This  type  was  introduced  in  place  of  short  for  stjilink  (see 

5.6.1)  in  response  to  an  objection  that  short  was  too  small. 

offj  This  type  is  used  only  in  Iseek (),  fcntl(),  and  <sys/stat .  h>. 

Many  implementations  would  have  difficulties  if  it  were  defined 
as  anything  other  than  long.  Requiring  an  integral  type  limits  | 
the  capabilities  of  Iseek  ()  to  four  gigabytes.  See  the  description  | 
of  lread()  in  B.6.4.  Also,  the  C  Standard  {2}  supplies  routines  | 
that  use  larger  types:  see  fgetposO  and  fsetposi.)  in  B.6.5.3.  | 

pidj  The  inclusion  of  this  symbol  was  controversial  because  it  is  tied 

to  the  issue  of  the  representation  of  a  process  ID  as  a  number. 
From  the  point  of  view  of  a  portable  application,  process  IDs 
should  be  “magic  cookies”2)  that  are  produced  by  calls  such  as 
fork (),  used  by  calls  such  as  waitpidi)  or  kill(),  and  not  other¬ 
wise  analyzed  (except  that  the  sign  is  used  as  a  flag  for  certain 
operations). 

The  concept  of  a  {PID_MAX}  value  interacted  with  this  in  early 
drafts.  Treating  process  IDs  as  an  opaque  type  both  removes 
the  requirement  for  {PID_MAX}  and  allows  systems  to  be  more 
flexible  in  providing  process  IDs  that  span  a  large  range  of 
values,  or  a  small  one. 


2)  An  historical  term  meaning:  “An  opaque  object,  or  token,  of  determinate  size,  whose  significance 
is  known  only  to  the  entity  which  created  it.  An  entity  receiving  such  a  token  from  the 
generating  entity  may  only  make  such  use  of  the  ‘cookie’  as  is  defined  and  permitted  by  the 
supplying  entity.” 
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ssizej 


uid_t 


Since  the  values  in  uid_t,gid_t,  and pidj  will  be  numbers  gen¬ 
erally,  and  potentially  both  large  in  magnitude  and  sparse, 
applications  that  are  based  on  arrays  of  objects  of  this  type  are 
unlikely  to  be  fully  portable  in  any  case.  Solutions  that  treat 
them  as  magic  cookies  will  be  portable. 

{CHILD_MAX}  precludes  the  possibility  of  a  “toy  implementa¬ 
tion,”  where  there  would  only  be  one  process. 

This  is  intended  to  be  a  signed  analog  of  sizejt.  The  wording  is  | 
such  that  an  implementation  may  either  choose  to  use  a  longer  | 
type  or  simply  to  use  the  signed  version  of  the  type  that  under-  | 
lies  sizejt.  All  functions  that  return  ssizejt  [ read{ )  and  write ()]  | 

describe  as  “implementation  defined”  the  result  of  an  input  | 
exceeding  {SSIZE_MAX}.  It  is  recognized  that  some  implemen-  | 
tations  might  have  int s  that  are  smaller  than  size_t.  A  port-  | 
able  application  would  be  constrained  not  to  perform  I/O  in  | 
pieces  larger  than  {SSIZE_MAX},  but  a  portable  application  | 
using  extensions  would  be  able  to  use  the  full  range  if  the  | 
implementation  provided  an  extended  range,  while  still  having  | 
a  single  type-compatible  interface.  | 

The  symbols  sizejt  and  ssizejt  are  also  required  in  | 
<unist d .  h>  to  minimize  the  changes  needed  for  calls  to  read{ )  | 

and  write().  Implementors  are  reminded  that  it  must  be  possi-  | 
ble  to  include  both  <sys/types . h>  and  <unistd.h>  in  the  | 
same  program  (in  either  order)  without  error.  | 

Before  the  addition  of  this  type,  the  data  types  used  to 
represent  these  values  varied  throughout  early  drafts.  The 
<sys/stat . h>  header  defined  these  values  as  type  short,  the 
<passwd.h>  file  (now  <pwd.h>  and  <grp.h>)  used  an  int, 
and  getuidi)  returned  an  int.  In  response  to  a  strong  objection 
to  the  inconsistent  definitions,  all  the  types  to  were  switched  to  | 
uid_t.  | 

In  practice,  those  historical  implementations  that  use  varying 
types  of  this  sort  can  typedef  uidj  to  short  with  no  serious 
consequences. 

The  problem  associated  with  this  change  concerns  object  com¬ 
patibility  after  structure  size  changes.  Since  most  implementa¬ 
tions  will  define  uidjt  as  a  short,  the  only  substantive  change 
will  be  a  reduction  in  the  size  of  the  passwd  structure.  Conse¬ 
quently,  implementations  with  an  overriding  concern  for  object 
compatibility  can  pad  the  structure  back  to  its  current  size.  For 
that  reason,  this  problem  was  not  considered  critical  enough  to 
warrant  the  addition  of  a  separate  type  to  POSIX.l. 

The  types  uidjt  and  gid_t  are  magic  cookies.  There  is  no 
{UID_MAX}  defined  by  POSIX.l,  and  no  structure  imposed  on 
uid_t  and  gidj  other  than  that  they  be  positive  arithmetic 
types.  (In  fact,  they  could  be  unsigned  char.)  There  is  no  max¬ 
imum  or  minimum  specified  for  the  number  of  distinct  user  or 
group  IDs. 
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B.2.6  Environment  Description 

The  variable  environ  is  not  intended  to  be  declared  in  any  header,  but  rather  to  be  | 
declared  by  the  user  for  accessing  the  array  of  strings  that  is  the  environment.  | 
This  is  the  traditional  usage  of  the  symbol.  Putting  it  into  a  header  could  break  | 
some  programs  that  use  the  symbol  for  their  own  purposes. 

LC_*  The  description  of  the  environment  variable  names  starting 

with  the  characters  “LC_”  acknowledges  the  fact  that  the  inter¬ 
faces  presented  in  the  current  version  of  POSIX.  1  are  not  com¬ 
plete  and  may  be  extended  as  new  international  functionality  is 
required.  In  the  C  Standard  {2},  names  preceded  by  “LC_”  are  | 
reserved  in  the  name  space  for  future  categories. 

To  avoid  name  clashes,  new  categories  and  environment  vari¬ 
ables  are  divided  into  two  classifications:  implementation 
independent  and  implementation  dependent. 

Implementation-independent  names  will  have  the  following 
format: 

LC  _NAME 

where  NAME  is  the  name  of  the  new  category  and  environment 
variable.  Capital  letters  must  be  used  for  implementation- 
independent  names. 

Implementation-dependent  names  must  be  in  lowercase  letters, 
as  below: 

LC  jiame 

PATH  Many  historical  implementations  of  the  Bourne  shell  do  not 

interpret  a  trailing  colon  to  represent  the  current  working 
directory  and  are  thus  nonconforming.  The  C  Shell  and  the 
KornShell  conform  to  POSIX.1  on  this  point.  The  usual  name  of 
dot  may  also  be  used  to  refer  to  the  current  working  directory. 

TZ  See  8.1.1  for  an  explanation  of  the  format. 

LOGNAME  4.3BSD  uses  the  environment  variable  USER  for  this  purpose. 

In  most  implementations,  the  value  of  such  a  variable  is  easily 
forged,  so  security-critical  applications  should  rely  on  other 
means  of  determining  user  identity.  LOGNAME  is  required  to 
be  constructed  from  the  portable  filename  character  set  for  rea¬ 
sons  of  interchange.  No  diagnostic  condition  is  specified  for 
violating  this  rule,  and  no  requirement  for  enforcement  exists. 
The  intent  of  the  requirement  is  that  if  extended  characters  are 
used,  the  “guarantee”  of  portability  implied  by  a  standard  is 
voided.  (See  also  B.2.2.2.) 

The  following  environment  variables  have  been  used  historically  as  indicated. 
However,  such  use  was  either  so  variant  as  to  not  be  amenable  to  standardization 
or  to  be  relevant  only  to  other  facilities  not  specified  in  POSIX.1,  and  they  have 
therefore  been  excluded.  They  may  or  may  not  be  included  in  future  POSIX  stan¬ 
dards.  Until  then,  writers  of  conforming  applications  should  be  aware  that 
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1364 


1363 


1360 


1361 


1362 


1359 


details  of  the  use  of  these  variables  are  likely  to  vary  in  different  contexts. 
IFS  Characters  used  as  field  separators. 

MAIL  System  mailer  information. 

PS1  Prompting  string  for  interactive  programs. 

PS2  Prompting  string  for  interactive  programs. 

SHELL  The  shell  command  interpreter  name. 


1365  B.2.7  C  Language  Definitions 

1366  The  construct  <name  .  h>  for  headers  is  also  taken  from  the  C  Standard  {2}. 

1367  B.2.7.1  Symbols  From  the  C  Standard 

1368  The  reservation  of  identifiers  is  paraphrased  from  the  C  Standard  {2}.  The  text  is  | 

1369  included  because  it  needs  to  be  part  of  POSIX.1,  regardless  of  possible  changes  in  | 

1370  future  versions  of  the  C  Standard  {2}.  The  reservation  of  other  namespaces  is  par-  | 

1371  ticularly  for  <errno  .  h>. 

1372  These  identifiers  may  be  used  by  implementations,  particularly  for  feature  test 

1373  macros.  Implementations  should  not  use  feature  test  macro  names  that  might  be 

1374  reasonably  used  by  a  standard. 

1375  The  requirement  for  representing  the  number  of  clock  ticks  in  24  h  refers  to  the  | 

1376  interval  defined  by  POSIX.1,  not  to  the  interval  defined  by  the  C  Standard  {2}.  | 

1377  Including  headers  more  than  once  is  a  reasonably  common  practice,  and  it  should 

1378  be  carried  forward  from  the  C  Standard  {2}.  More  significantly,  having  definitions 

1379  in  more  than  one  header  is  explicitly  permitted.  Where  the  potential  declaration 

1380  is  “benign”  (the  same  definition  twice)  the  declaration  can  be  repeated,  if  that  is 

1381  permitted  by  the  compiler.  (This  is  usually  true  of  macros,  for  example.)  In  those 

1382  situations  where  a  repetition  is  not  benign  (e.g.,  typedefs),  conditional  compilation 

1383  must  be  used.  The  situation  actually  occurs  both  within  the  C  Standard  {2}  and 

1384  within  POSIX1:  timejt  should  be  in  <sys/types .  h>,  and  the  C  Standard  {2} 

1385  mandates  that  it  be  in  <time  .h>.  POSIX.1  requires  using  <sys/types  .h>  with 

1386  <time  .  h>  because  of  the  common-usage  environment. 

1387  B.2.7.2  POSIX.1  Symbols 

1388  This  subclause  addresses  the  issue  of  “namespace  pollution.”  The  C  Standard  {2}  | 

1389  requires  that  the  namespace  beyond  what  it  reserves  not  be  altered  except  by 

1390  explicit  action  of  the  application  writer.  This  subclause  defines  the  actions  to  add  | 

1391  the  POSIX.1  symbols  for  those  headers  where  both  the  C  Standard  {2}  and  POSIX.1  | 

1392  need  to  define  symbols.  Where  there  are  nonoverlapping  uses  of  headers,  there  is 

1393  no  problem. 

1394  The  list  of  symbols  defined  in  the  C  Standard  {2}  is  summarized  in  the  rationale  | 

1395  associated  with  Annex  C.  I 

1396  Implementors  should  note  that  the  requirement  on  type  conversion  disallows  | 
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using  an  older  declaration  as  a  prototype  and  in  effect  requires  that  the  number  of  | 
arguments  in  the  prototype  match  that  given  in  POSIX.1.  | 

When  headers  are  used  to  provide  symbols,  there  is  a  potential  for  introducing 
symbols  that  the  application  writer  cannot  predict.  Ideally,  each  header  should 
only  contain  one  set  of  symbols,  but  this  is  not  practical  for  historical  reasons. 
Thus,  the  concept  of  feature  test  macros  is  included.  This  is  done  in  a  general 
manner  because  it  is  expected  that  future  additions  to  POSIX.1  and  other  related 
standards  will  have  this  same  problem.  (Future  standards  not  constrained  by 
historical  practice  should  avoid  the  problem  by  using  new  header  files  rather  than 
using  ones  already  extant.) 

This  idea  is  split  into  two  subclauses:  2.7.2. 1  covers  the  case  of  the  C  Standard  | 
{2}  conformant  systems,  where  the  requirements  of  the  C  Standard  {2}  are  that 
unless  specifically  requested  the  application  will  not  see  any  other  symbols,  and 
“Common  Usage,”  where  the  default  set  of  symbols  is  not  well  controlled  and 
backwards  compatibility  is  an  issue. 

The  common  usage  case  is  the  more  difficult  to  define.  In  the  C  Standard  {2}  case, 
each  feature  test  macro  simply  adds  to  the  possible  symbols.  In  common  usage, 
_POSIX_SOURCE  is  a  special  case  in  that  it  reduces  the  set  to  the  sum  of  the 
C  Standard  {2}  and  POSIX.1.  (The  developers  of  the  C  Standard  {2}  will  determine  | 
if  they  want  a  similar  macro  to  limit  the  features  to  just  the  C  Standard  {2};  the 
wording  permits  this  because  under  those  circumstances  _POSIX_SOURCE  would 
be  just  another  ordinary  feature  test  macro.  The  only  order  requirement  is 
“before  headers.”) 

If  _POSIX_SOURCE  is  not  defined  in  a  common-usage  environment,  the  user 
presumably  gets  the  same  results  as  in  previous  releases.  Some  applications  may 
today  be  conformant  without  change,  so  they  would  continue  to  compile  as  long  as 
common  usage  is  provided.  When  the  C  Standard  {2}  is  the  default  they  will  have 
to  change  (unless  they  are  already  C  Standard  {2}  conformant),  but  this  can  be 
done  gradually. 

Note  that  the  net  result  of  defining  _POSIX_SOURCE  at  the  beginning  of  a  pro¬ 
gram  is  in  either  case  the  same:  the  implementation-defined  symbols  are  only 
visible  if  they  are  requested.  (But  if  _POSIX_SOURCE  is  not  used,  the  implemen¬ 
tation  default,  which  is  probably  backwards  compatible,  determines  their 
visibility.) 

The  area  of  namespace  pollution  versus  additions  to  structures  is  difficult  because  | 
of  the  macro  structure  of  C.  The  following  discussion  summarizes  all  the  various  | 
problems  with  and  objections  to  the  issue.  j 

Note  the  phrase  “user  defined  macro.”  Users  are  not  permitted  to  define  macro  | 
names  (or  any  other  name)  beginning  with  _[A-Z_].  Thus,  the  conflict  cannot  | 
occur  for  symbols  reserved  to  the  vendor’s  namespace,  and  the  permission  to  add  | 
fields  automatically  applies,  without  qualification,  to  those  symbols. 

(1)  Data  structures  (and  unions)  need  to  be  defined  in  headers  by  implemen-  | 
tations  to  meet  certain  requirements  of  POSIX.1  and  the  C  Standard  {2}. 

(2)  The  structures  defined  by  POSIX.1  are  typically  minimal,  and  any  practi-  | 
cal  implementation  would  wish  to  add  fields  to  these  structures  either  to  | 
hold  additional  related  information  or  for  backwards  compatibility  (or  | 
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both).  Future  standards  (and  de  facto  standards)  would  also  wish  to  add 
to  these  structures.  Issues  of  field  alignment  make  it  impractical  (at 
least  in  the  general  case)  to  simply  omit  fields  when  they  are  not  defined 
by  the  particular  standard  involved. 

Struct  dirent  is  an  example  of  such  a  minimal  structure  (although  one 
could  argue  about  whether  the  other  fields  need  visible  names).  The 
st_rdev  field  of  most  implementations’  stat  structure  is  a  common  exam¬ 
ple  where  extension  is  needed  and  where  a  conflict  could  occur. 

(3)  Fields  in  structures  are  in  an  independent  namespace,  so  the  addition  of 
such  fields  presents  no  problem  to  the  C  language  itself  in  that  such 
names  cannot  interact  with  identically  named  user  symbols  because 
access  is  qualified  by  the  specific  structure  name. 

(4)  There  is  an  exception  to  this:  macro  processing  is  done  at  a  lexical  level. 
Thus,  symbols  added  to  a  structure  might  be  recognized  as  user-provided 
macro  names  at  the  location  where  the  structure  is  declared.  This  only 
can  occur  if  the  user-provided  name  is  declared  as  a  macro  before  the 
header  declaring  the  structure  is  included.  The  user’s  use  of  the  name 
after  the  declaration  cannot  interfere  with  the  structure  because  the  sym¬ 
bol  is  hidden  and  only  accessible  through  access  to  the  structure. 
Presumably,  the  user  would  not  declare  such  a  macro  if  there  was  an 
intention  to  use  that  field  name. 

(5)  Macros  from  the  same  or  a  related  header  might  use  the  additional  fields 
in  the  structure,  and  those  field  names  might  also  collide  with  user  mac¬ 
ros.  Although  this  is  a  less  frequent  occurrence,  since  macros  are 
expanded  at  the  point  of  use,  no  constraint  on  the  order  of  use  of  names 
can  apply. 

(6)  An  “obvious”  solution  of  using  names  in  the  reserved  namespace  and 
then  redefining  them  as  macros  when  they  should  be  visible  does  not 
work  because  this  has  the  effect  of  exporting  the  symbol  into  the  general 
namespace.  For  example,  given  a  (hypothetical)  system-provided  header 
<h .  h>,  and  two  parts  of  a  C  program  in  a .  c  and  b .  c: 

In  header  <h .  h>: 

struct  foo  { 

int _ i; 

} 

#if def  _FEATURE_TEST 

♦define  i _ i; 

#endif 

In  file  a .  c: 

♦include  h.h 
extern  int  i; 

In  file  b .  c: 
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extern  int  i; 

The  symbol  that  the  user  thinks  of  as  i  in  both  files  has  an  external 

name  of  " _ i"  in  a .  c;  the  same  symbol  i  in  b .  c  has  an  external  name 

"i"  (ignoring  any  hidden  manipulations  the  compiler  might  perform  on 
the  names).  This  would  cause  a  mysterious  name  resolution  problem 
when  a .  o  and  b .  o  are  linked. 

Simply  avoiding  definition  then  causes  alignment  problems  in  the 
structure. 

A  structure  of  the  form 

struct  foo  { 

union  { 

int _ i  ; 

#ifdef  _FEATURE_TEST 
int  i; 

#endif 

} _ ii; 

} 

does  not  work  because  the  name  of  the  logical  field  i  is  " _ ii .  i",  and 

introduction  of  a  macro  to  restore  the  logical  name  immediately  reintro¬ 
duces  the  problem  discussed  previously  (although  its  manifestation 
might  be  more  immediate  because  a  syntax  error  would  result  if  a  recur¬ 
sive  macro  did  not  cause  it  to  fail  first). 

(7)  A  more  workable  solution  would  be  to  declare  the  structure: 

struct  foo  { 

#if def  _FEATURE_TEST 
int  i  ; 

#else 

int _ i; 

#endif 

} 

However,  if  a  macro  (particularly  one  required  by  a  standard)  is  to  be 
defined  that  uses  this  field,  two  must  be  defined:  one  that  uses  i,  the 

other  that  uses _ i.  If  more  than  one  additional  field  is  used  in  a  macro 

and  they  are  conditional  on  distinct  combinations  of  features,  the  com¬ 
plexity  goes  up  as  2n. 

All  this  leaves  a  difficult  situation:  vendors  must  provide  very  complex  headers  to 
deal  with  what  is  conceptually  simple  and  safe:  adding  a  field  to  a  structure.  It  is 
the  possibility  of  user-provided  macros  with  the  same  name  that  makes  this 
difficult. 

Several  alternatives  were  proposed  that  involved  constraining  the  user’s  access  to 
part  of  the  namespace  available  to  the  user  (as  specified  by  the  C  Standard  {2}). 
In  some  cases,  this  was  only  until  all  the  headers  had  been  included.  There  were 
two  proposals  discussed  that  failed  to  achieve  consensus: 
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—  Limiting  it  for  the  whole  program. 

—  Restricting  the  use  of  identifiers  containing  only  uppercase  letters  until 
after  all  system  headers  had  been  included.  It  was  also  pointed  out  that 
because  macros  might  wish  to  access  fields  of  a  structure  (and  macro 
expansion  occurs  totally  at  point  of  use)  restricting  names  in  this  way 
would  not  protect  the  macro  expansion,  and  thus  the  solution  was 
inadequate. 

It  was  finally  decided  that  reservation  of  symbols  would  occur,  but  as  constrained. 

The  current  wording  also  allows  the  addition  of  fields  to  a  structure,  but  requires 
that  user  macros  of  the  same  name  not  interfere.  This  allows  vendors  to  either: 

—  Not  create  the  situation  [do  not  extend  the  structures  with  user-accessible 
names  or  use  the  solution  in  (7)  above]  or 

—  Extend  their  compilers  to  allow  some  way  of  adding  names  to  structures 
and  macros  safely. 

There  are  at  least  two  ways  that  the  compiler  might  be  extended:  add  new 
preprocessor  directives  that  turn  off  and  on  macro  expansion  for  certain  symbols 
(without  changing  the  value  of  the  macro)  and  a  function  or  lexical  operation  that 
suppresses  expansion  of  a  word.  The  latter  seems  more  flexible,  particularly 
because  it  addresses  the  problem  in  macros  as  well  as  in  declarations. 

The  following  seems  to  be  a  possible  implementation  extension  to  the  C  language 
that  will  do  this:  any  token  that  during  macro  expansion  is  found  to  be  preceded 
by  three  #  symbols  shall  not  be  further  expanded  in  exactly  the  same  way  as 
described  for  macros  that  expand  to  their  own  name  as  in  section  3. 8.3. 4  of  the 
C  Standard  {2}.  A  vendor  may  also  wish  to  implement  this  as  an  operation  that  is 
lexically  a  function,  which  might  be  implemented  as 

#define _ safe_name  (x)  ###x 

Using  a  function  notation  would  insulate  vendors  from  changes  in  standards  until 
such  a  functionality  is  standardized  (if  ever).  Standardization  of  such  a  function 
would  be  valuable  because  it  would  then  permit  third  parties  to  take  advantage  of 
it  portably  in  software  they  may  supply. 

The  symbols  that  are  “explicitly  permitted,  but  not  required  by  this  part  of 
ISO/IEC  9945”  include  those  classified  below.  (That  is,  the  symbols  classified 
below  might,  but  are  not  required  to,  be  present  when  _POSIX_SOURCE  is 
defined.) 

—  Symbols  in  2.8  and  2.9  that  are  defined  to  indicate  support  for  options  or 
limits  that  are  constant  at  compile-time. 

—  Symbols  in  the  namespace  reserved  for  the  implementation  by  the 
C  Standard  {2}. 

—  Symbols  in  a  namespace  reserved  for  a  particular  type  of  extension  (e.g., 
type  names  ending  with  _t  in  <sy s/types  .  h>). 

—  Additional  members  of  structures  or  unions  whose  names  do  not  reduce  the 
namespace  reserved  for  applications  (see  B.2.7.2). 
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1572  The  phrase  “when  that  header  is  included”  was  chosen  to  allow  any  fine  structure  | 

1573  of  auxiliary  headers  the  implementor  may  choose  to  use,  as  long  as  the  net  result  | 

1574  is  as  required.  | 

1575  There  are  several  common  environments  available  today  where  a  feature  test 

1576  macro  would  be  useful  to  applications  programmers  during  the  transition  to 

1577  standard-conforming  environments  from  certain  common  historical  environments. 

1578  The  symbols  in  Table  B-l,  derived  from  common  porting  bases  and  industry 


1579 

specifications  are  suggested. 

1580 

Table  B-l  - 

Suggested  Feature  Test  Macros 

1581 

1582 

Symbol 

Description 

1583 

_V7 

Version  7 

1584 

_BSD 

General  BSD  systems 

1585 

_BSD4_2 

4.2BSD 

1586 

_BSD4_3 

4.3BSD 

1587 

_SYSIII 

System  III 

1588 

_SYSV 

System  V.l,  V.2 

1589 

_SYSV3 

System  V.3 

1590 

_XP  Gn 

X/Open  Portability  Guide,  Issue  n 

1591 

_USR_GROUP  The  1984  /usr/group  standard 

1592 

1593  Only  symbols  that  are  actually  in  the  porting  base  or  industry  specification  should 

1594  be  enabled  by  these  symbols. 

1595  Feature  test  macros  for  implementation  extensions  will  also  probably  be  required. 

1596  Quite  a  few  of  these  are  traditionally  available,  but  are  in  violation  of  the  intent  of 

1597  namespace  pollution  control.  These  can  be  made  conforming  simply  by  prefixing 

1598  them  with  an  underscore.  Symbols  beginning  with  “_POSIX”  are  strongly 

1599  discouraged,  as  they  will  probably  be  used  by  later  revisions  of  POSIX.  1. 

1600  The  environment  for  compilation  has  traditionally  been  fairly  portable  in  histori- 

1601  cal  systems,  but  during  the  transition  to  the  C  Standard  {2}  there  will  be  confu- 

1602  sion  about  how  to  specify  that  a  C  Standard  {2}  compiler  is  expected,  as  considera- 

1603  tions  of  backwards  compatibility  will  constrain  many  implementors  from  provid- 

1604  ing  a  conformant  environment  replacing  the  traditional  one.  This  concern  has 

1605  more  to  do  with  the  issues  of  namespace  than  with  the  syntax  of  the  language 

1606  accepted,  which  is  highly  compatible. 

1607  For  systems  that  are  sufficiently  similar  to  traditional  UNIX  systems  for  this  to  | 

1608  make  sense,  it  is  suggested  that  if  a  compilation  line  of  the  form  | 

1609  CC  -D _ STDC _ .  .  . 

1610  is  provided,  that  the  system  provide  an  environment  that  is  conformant  with  the 

1611  C  Standard  {2},  at  least  with  respect  to  namespace.  | 

1612  It  was  decided  to  use  feature  test  macros,  rather  than  the  inclusion  of  a  header, 

1613  both  because  cunistd .  h>  was  already  in  use  and  would  itself  have  this  problem, 

1614  and  because  the  underlying  mechanism  would  probably  have  been  this  anyway, 

1615  but  in  a  less  flexible  fashion. 
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1616  POSIX.1  requires  that  headers  be  included  in  all  cases,  although  it  is  not  directly 

1617  clear  from  the  text  at  this  point  in  the  standard.  If  a  function  does  not  need  any 

1618  special  types,  then  it  must  be  declared  in  <unistd.h>,  as  stated  here.  If  it  does 

1619  require  something  special,  then  it  has  an  associated  header,  and  the  program  will 

1620  not  compile  without  that  header. 

1621  B.2.7.3  Headers  and  Function  Prototypes 

1622  The  statement  that  names  need  not  be  carried  forward  literally  exists  for  several 

1623  reasons.  These  include  the  fact  that  some  vendors  may  historically  use  other 

1624  names  and  that  the  names  are  irrelevant  to  application  portability.  More  impor- 

1625  tantly,  because  of  the  pervasive  nature  of  C  macros,  a  declaration  of  the  form: 

1626  kill  (pid_t  pid,  int  sig)  ; 

1627  could  be  seriously  undermined  by  a  (perfectly  valid)  user  declaration  of  the  form: 

1628  #define  pid  statusstruct  .pidinf o 


1629  B.2.8  Numerical  Limits 

1630  This  subclause  clarifies  the  scope  and  mutability  of  several  classes  of  limits. 


1631  B.2.8.1  C  Language  Limits 


1632  See  also  2.7  and  B. 1.1.1. 


1633 

1634 

1635 


{CHARJMIN}  It  is  possible  to  tell  if  the  implementation  supports  native  char¬ 
acter  comparison  as  signed  or  unsigned  by  comparing  this  limit 
to  zero. 


1636  {WORD_BIT}  This  limit  has  been  omitted,  as  it  is  not  referenced  elsewhere  in 

1637  POSIX.1. 


1638  No  limits  are  given  in  climits  .h>  for  floating  point  values  because  none  of  the 

1639  functions  in  POSIX.1  use  floating  point  values,  and  all  the  functions  that  do  that 

1640  are  imported  from  the  C  Standard  {2}  by  8.1,  as  are  the  limits  that  apply  to  the 

1641  floating  point  values  associated  with  them. 

1642  Though  limits  to  the  addresses  to  system  calls  were  proposed,  they  were  not 

1643  included  in  POSIX.1  because  it  is  not  clear  how  to  implement  them  for  the  range  of 

1644  systems  being  considered,  and  no  complete  proposal  was  ever  received.  Limits  | 

1645  regarding  hardware  register  characteristics  were  similarly  proposed  and  not 

1646  attempted. 


1647  B.2.8.2  Minimum  Values 

1648  There  has  been  confusion  about  the  minimum  maxima,  and  when  that  is  under- 

1649  stood  there  is  still  a  concern  about  providing  ways  to  allocate  storage  based  on  the 

1650  symbols.  This  is  particularly  true  for  those  in  2.8.4  where  an  indeterminate  value 

1651  will  leave  the  programmer  with  no  symbol  upon  which  to  fall  back. 

1652  Providing  explicit  symbols  for  the  minima  (from  the  implementor’s  point  of  view, 

1653  or  maxima  from  the  the  application’s  point  of  view)  helps  to  resolve  possible 
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confusion.  Symbols  are  still  provided  for  the  actual  value,  and  it  is  expected  that 
many  applications  will  take  advantage  of  these  larger  values,  but  they  need  not 
do  so  unless  it  is  to  their  advantage.  Where  the  values  in  this  subclause  are  ade-  | 
quate  for  the  application,  it  should  use  them.  These  are  given  symbolically  both  | 
because  it  is  easier  to  understand  and  because  the  values  of  these  symbols  could 
change  between  revisions  of  POSIX.1.  Arguments  to  “good  programming  practice” 
also  apply. 

B.2.8.3  Run-Time  Increasable  Values 

The  heading  of  the  far-right  column  of  the  table  is  given  as  “Minimum  Value” 
rather  than  “Value”  in  order  to  emphasize  that  the  numbers  given  in  that  column 
are  minimal  for  the  actual  values  a  specific  implementation  is  permitted  to  define 
in  its  <limits.h>.  The  values  in  the  actual  <limits.h>  define,  in  turn,  the 
maximum  amount  of  a  given  resource  that  a  Conforming  POSIX.1  Application  can 
depend  on  finding  when  translated  to  execute  on  that  implementation.  A  Con¬ 
forming  POSIX.1  Application  Using  Extensions  must  function  correctly  even  if  the 
value  given  in  <limits.h>  is  the  minimum  that  is  specified  in  POSIX.1.  (The 
application  may  still  be  written  so  that  it  performs  more  efficiently  when  a  larger 
value  is  found  in  <limits.h>.)  A  conforming  implementation  must  provide  at 
least  as  much  of  a  particular  resource  as  that  given  by  the  value  in  POSIX.1.  An 
implementation  that  cannot  meet  this  requirement  (a  “toy  implementation”)  can¬ 
not  be  a  conforming  implementation. 

B.2.8.4  Run-Time  Invariant  Values  (Possibly  Indeterminate) 

{CHILD_MAX}  This  name  can  be  misleading.  This  limit  applies  to  all 
processes  in  the  system  with  the  same  user  ID,  regardless  of 
ancestry. 

B.2.8.5  Pathname  Variable  Values 

{MAX_INPUT}  Since  the  only  use  of  this  limit  is  in  relation  to  terminal  input 
queues,  it  mentions  them  specifically.  This  limit  was  originally 
named  {MAX_CHAR}.  Application  writers  should  use 
{MAX_INPUT}  primarily  as  an  indication  of  the  number  of  bytes 
that  can  be  written  as  a  single  unit  by  one  Conforming  POSIX.1 
Application  Using  Extensions  communicating  with  another  via 
a  terminal  device.  It  is  not  implied  that  input  lines  received 
from  terminal  devices  always  contain  {MAX_INPUT}  bytes  or 
fewer:  an  application  that  attempts  to  read  more  than 
{MAX_INPUT}  bytes  from  a  terminal  may  receive  more  than 
{MAXJNPUT}  bytes. 

It  is  not  obvious  that  {MAX_INPUT}  is  of  direct  value  to  the 
application  writer.  The  existence  of  such  a  value  (whatever  it 
may  be)  is  directly  of  use  in  understanding  how  the  tty  driver 
works  (particularly  with  respect  to  flow  control  and  dropped 
characters).  The  value  can  be  determined  by  finding  out  when 
flow  control  takes  effect  (see  the  description  of  IXOFF  in 
7.1.2. 2). 
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Understanding  that  the  limit  exists  and  knowing  its  magnitude 
is  important  to  making  certain  classes  of  applications  work 
correctly.  It  is  unlikely  to  be  used  in  an  application,  but  its 
presence  makes  POSIX1  clearer. 

{PATH_MAX}  A  Conforming  POSIX.1  Application  or  Conforming  POSIX.1 
Application  Using  Extensions  that,  for  example,  compiles  to  use 
different  algorithms  depending  on  the  value  of  {PATH_MAX} 
should  use  code  such  as: 

#if  defined (path_max)  &&  path_max  <  512 
#else 

#i£  defined (path_max)  /*  path_max  >=  512  */ 

#else  /*  path_max  indeterminate  */ 

#endif 

#endif 

This  is  because  the  value  tends  to  be  very  large  or  indeter¬ 
minate  on  most  historical  implementations  (it  is  arbitrarily 
large  on  System  V).  On  such  systems  there  is  no  way  to  quan¬ 
tify  the  limit,  and  it  seems  counterproductive  to  include  an 
artificially  small  fixed  value  in  <limits  .  h>  in  such  cases. 


B.2.9  Symbolic  Constants 

B.2.9.1  Symbolic  Constants  for  the  access  ()  Function 

There  is  no  additional  rationale  provided  for  this  subclause. 

B.2.9.2  Symbolic  Constants  for  the  IseekO  Function 

There  is  no  additional  rationale  provided  for  this  subclause. 

B.2.9.3  Compile-Time  Symbolic  Constants  for  Portability  Specifications 

The  purpose  of  this  material  is  to  allow  an  application  developer  to  have  a  chance  | 
to  determine  whether  a  given  application  would  run  (or  run  well)  on  a  given 
implementation.  To  this  purpose  has  been  added  that  of  simplifying  development 
of  verification  suites  for  POSIX.1.  The  constants  given  here  were  originally  pro-  | 
posed  for  a  separate  file,  <posix .  h>,  but  it  was  decided  that  they  should  appear  | 
in<unistd.h>  along  with  other  symbolic  constants.  | 

B.2.9.4  Execution-Time  Symbolic  Constants  for  Portability  Specifications 

Without  the  addition  of  LPOSIX_NO_TRUNC}  and  {_PC_NO_TRUNC}  to  this  list, 
POSIX.1  says  nothing  about  the  effect  of  a  pathname  component  longer  than 
{NAME_MAX}.  There  are  only  two  effects  in  common  use  in  implementations: 
truncation  or  an  error.  It  is  desirable  to  limit  allowable  behavior  to  these  two 
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1737  cases.  It  is  also  desirable  to  permit  applications  to  determine  what  an 

1738  implementation’s  behavior  is  because  services  that  are  available  with  one 

1739  behavior  may  be  impractical  to  provide  with  the  other.  However,  since  the 

1740  behavior  may  vary  from  one  file  system  to  another,  it  may  be  necessary  to  use 

1741  pathconfi )  to  resolve  it. 


1742  B.3  Process  Primitives 

1743  Consideration  was  given  to  enumerating  all  characteristics  of  a  process  defined  by  | 

1744  POSIX.  1  and  describing  each  function  in  terms  of  its  effects  on  those  characteris- 

1745  tics,  rather  than  English  text.  This  is  quite  different  from  any  known  descriptions 

1746  of  historical  implementations,  and  it  was  not  certain  that  this  could  be  done  ade-  | 

1747  quately  and  completely  enough  to  produce  a  usable  standard.  Providing  such 

1748  descriptions  in  addition  to  the  text  was  also  considered.  This  was  not  done 

1749  because  it  would  provide  at  best  two  redundant  descriptions,  and  more  likely  two 

1750  descriptions  with  subtle  inconsistencies. 

1751  B.3.1  Process  Creation  and  Execution 

1752  Running  a  new  program  takes  two  steps.  First  the  existing  process  (the  parent) 

1753  calls  the  fork()  function,  producing  a  new  process  (the  child),  which  is  a  copy  of 

1754  itself.  One  of  these  processes  (normally,  but  not  necessarily,  the  child)  then  calls 

1755  one  of  the  exec  functions  to  overlay  itself  with  a  copy  of  the  new  process  image. 

1756  If  the  new  program  is  to  be  run  synchronously  (the  parent  suspends  execution 

1757  until  the  child  completes),  the  parent  process  then  uses  either  the  wait{)  or  wait- 

1758  pid( )  function.  If  the  new  program  is  to  be  run  asynchronously,  it  does  not  suffice 

1759  to  simply  omit  the  wait()  or  waitpidi)  call,  because  after  the  child  terminates  it 

1760  continues  to  hold  some  resources  until  it  is  waited  for.  A  common  way  to  produce 

1761  (“spawn”)  a  descendant  process  that  does  not  need  to  be  waited  on  is  to  fork  ()  to 

1762  produce  a  child  and  wait()  on  the  child.  The  child  fork ()s  again  to  produce  a 

1763  grandchild.  The  child  then  exits  and  the  parent’s  wait()  returns.  The  grandchild 

1764  is  thus  disinherited  by  its  grandparent. 

1765  A  simpler  method  (from  the  programmer’s  point  of  view)  of  spawning  is  to  do 

1766  system ( "something  &"); 

1767  However,  this  depends  on  features  of  a  process  (the  shell)  that  are  outside  the 

1768  scope  of  POSIX.  1,  although  they  are  currently  being  addressed  by  the  working  | 

1769  group  preparing  ISO/IEC  9945-2  {B36}.  I 

1770  B.3. 1.1  Process  Creation 

1771  Many  historical  implementations  have  timing  windows  where  a  signal  sent  to  a  | 

1772  process  group  (e.g.,  an  interactive  SIGINT)  just  prior  to  or  during  execution  of 

1773  fork()  is  delivered  to  the  parent  following  the  fork ()  but  not  to  the  child  because 

1774  the  forki)  code  clears  the  child’s  set  of  pending  signals.  POSIX.1  does  not  require, 

1775  or  even  permit,  this  behavior.  However,  it  is  pragmatic  to  expect  that  problems  of 

1776  this  nature  may  continue  to  exist  in  implementations  that  appear  to  conform  to 
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POSIX.1  and  pass  available  verification  suites.  This  behavior  is  only  a  conse-  | 
quence  of  the  implementation  failing  to  make  the  interval  between  signal  genera¬ 
tion  and  delivery  totally  invisible.  From  the  application’s  perspective,  a  fork  ()  call 
should  appear  atomic.  A  signal  that  is  generated  prior  to  the  fork  ()  should  be 
delivered  prior  to  the  fork{).  A  signal  sent  to  the  process  group  after  the  fork{) 
should  be  delivered  to  both  parent  and  child.  The  implementation  might  actually 
initialize  internal  data  structures  corresponding  to  the  child’s  set  of  pending  sig¬ 
nals  to  include  signals  sent  to  the  process  group  during  the  fork ().  Since  the 
fork{ )  call  can  be  considered  as  atomic  from  the  application’s  perspective,  the  set 
would  be  initialized  as  empty  and  such  signals  would  have  arrived  after  the 
fork ().  See  also  B.3.3.1.2. 

One  approach  that  has  been  suggested  to  address  the  problem  of  signal  inheri¬ 
tance  across  fork()  is  to  add  an  [EINTR]  error,  which  would  be  returned  when  a 
signal  is  detected  during  the  call.  While  this  is  preferable  to  losing  signals,  it  was 
not  considered  an  optimal  solution.  Although  it  is  not  recommended  for  this  pur¬ 
pose,  such  an  error  would  be  an  allowable  extension  for  an  implementation. 

The  [ENOMEM]  error  value  is  reserved  for  those  implementations  that  detect  and 
distinguish  such  a  condition.  This  condition  occurs  when  an  implementation 
detects  that  there  is  not  enough  memory  to  create  the  process.  This  is  intended  to 
be  returned  when  [EAGAIN]  is  inappropriate  because  there  can  never  be  enough 
memory  (either  primary  or  secondary  storage)  to  perform  the  operation.  Because 
fork ()  duplicates  an  existing  process,  this  must  be  a  condition  where  there  is 
sufficient  memory  for  one  such  process,  but  not  for  two.  Many  historical  imple-  | 
mentations  actually  return  [ENOMEM]  due  to  temporary  lack  of  memory,  a  case  | 
that  is  not  generally  distinct  from  [EAGAIN]  from  the  perspective  of  a  portable 
application. 

Part  of  the  reason  for  including  the  optional  error  [ENOMEM]  is  because  the  SVID 
[B39]  specifies  it  and  it  should  be  reserved  for  the  error  condition  specified  there. 
The  condition  is  not  applicable  on  many  implementations. 

IEEE  Std  1003.1-1988  neglected  to  require  concurrent  execution  of  the  parent  and  | 
child  of  fork().  A  system  that  single-threads  processes  was  clearly  not  intended  | 
and  is  considered  an  unacceptable,  “toy  implementation”  of  POSIX.1.  The  only  | 
objection  anticipated  to  the  phrase  “executing  independently”  is  testability,  but  | 
this  assertion  should  be  testable.  Such  tests  require  that  both  the  parent  and  | 
child  can  block  on  a  detectable  action  of  the  other,  such  as  a  write  to  a  pipe  or  a  | 
signal.  An  interactive  exchange  of  such  actions  should  be  possible  for  the  system 
to  conform  to  the  intent  of  POSIX.1. 

The  [EAGAIN]  error  exists  to  warn  applications  that  such  a  condition  might  occur.  ] 
Whether  it  will  occur  or  not  is  not  in  any  practical  sense  under  the  control  of  the 
application  because  the  condition  is  usually  a  consequence  of  the  user’s  use  of  the 
system,  not  of  the  application’s  code.  Thus,  no  application  can  or  should  rely  upon  | 
its  occurrence  under  any  circumstances,  nor  should  the  exact  semantics  of  what 
concept  of  “user”  is  used  be  of  concern  to  the  application  writer.  Validation  writ-  | 
ers  should  be  cognizant  of  this  limitation. 
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B.3.1.2  Execute  a  File 

Early  drafts  of  POSIX.1  required  that  the  value  of argc  passed  to  main{)  be  “one  or  | 
greater.”  This  was  driven  by  the  same  requirement  in  drafts  of  the  C  Standard 
{2}.  In  fact,  historical  implementations  have  passed  a  value  of  zero  when  no  argu¬ 
ments  are  supplied  to  the  caller  of  the  exec  functions.  This  requirement  was 
removed  from  the  C  Standard  {2}  and  subsequently  removed  from  POSIX.1  as  well. 
The  POSIX.1  wording,  in  particular  the  use  of  the  word  “should,”  requires  a 
Strictly  Conforming  POSIX.1  Application  (see  1.3.3)  to  pass  at  least  one  argument 
to  the  exec  function,  thus  guaranteeing  that  argc  be  one  or  greater  when  invoked 
by  such  an  application.  In  fact,  this  is  good  practice,  since  many  existing  applica¬ 
tions  reference  argv  [0]  without  first  checking  the  value  of  argc . 

The  requirement  on  a  Strictly  Conforming  POSIX.1  Application  also  states  that 
the  value  passed  as  the  first  argument  be  a  filename  associated  with  the  process 
being  started.  Although  some  existing  applications  pass  a  pathname  rather  than 
a  filename  in  some  circumstances,  a  filename  is  more  generally  useful,  since  the 
common  usage  of  argu[0]  is  in  printing  diagnostics.  In  some  cases  the  filename 
passed  is  not  the  actual  filename  of  the  file;  for  example,  many  implementations 
of  the  login  utility  use  a  convention  of  prefixing  a  hyphen  (-)  to  the  actual 
filename,  which  indicates  to  the  command  interpreter  being  invoked  that  it  is  a 
“login  shell.” 

Some  systems  can  exec  shell  scripts.  This  functionality  is  outside  the  scope  of 
POSIX.1,  since  it  requires  standardization  of  the  command  interpreter  language  of 
the  script  and/or  where  to  find  a  command  interpreter.  These  fall  in  the  domain 
of  the  shell  and  utilities  standard,  currently  under  development  as  ISO/IEC  9945-2  | 

{B36}.  However,  it  is  important  that  POSIX.1  neither  require  nor  preclude  any  | 
reasonable  implementation  of  this  behavior.  In  particular,  the  description  of  the 
[ENOEXEC]  error  is  intended  to  permit  discretion  to  implementations  on  whether 
to  give  this  error  for  shell  scripts. 

One  common  historical  implementation  is  that  the  execl(),  execvi ),  execle (),  and  | 
execveO  functions  return  an  [ENOEXEC]  error  for  any  file  not  recognizable  as  exe¬ 
cutable,  including  a  shell  script.  When  the  execlp  ()  and  execvp  ()  functions 
encounter  such  a  file,  they  assume  the  file  to  be  a  shell  script  and  invoke  a  known 
command  interpreter  to  interpret  such  files.  These  implementations  of  execvp  () 
and  execlp  ()  only  give  the  [ENOEXEC]  error  in  the  rare  case  of  a  problem  with  the 
command  interpreter’s  executable  file.  Because  of  these  implementations  the 
[ENOEXEC]  error  is  not  mentioned  for  execlp ()  or  execvp  (),  although  implementa¬ 
tions  can  still  give  it. 

Another  way  that  some  historical  implementations  handle  shell  scripts  is  by  | 
recognizing  the  first  two  bytes  of  the  file  as  the  character  string  #  !  and  using  the  | 
remainder  of  the  first  line  of  the  file  as  the  name  of  the  command  interpreter  to 
execute. 

Some  implementations  provide  a  third  argument  to  main()  called  envp.  This  is 
defined  as  a  pointer  to  the  environment.  The  C  Standard  {2}  specifies  invoking 
main()  with  two  arguments,  so  implementations  must  support  applications  writ¬ 
ten  this  way.  Since  POSIX.1  defines  the  global  variable  environ ,  which  is  also  pro¬ 
vided  by  historical  implementations  and  can  be  used  anywhere  envp  could  be  | 
used,  there  is  no  functional  need  for  the  envp  argument.  Applications  should  use 
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the  getenvi)  function  rather  than  accessing  the  environment  directly  via  either 
envp  or  environ.  Implementations  are  required  to  support  the  two-argument  cal¬ 
ling  sequence,  but  this  does  not  prohibit  an  implementation  from  supporting  envp 
as  an  optional,  third  argument. 

POSIX.1  specifies  that  signals  set  to  SIG_IGN  remain  set  to  SIG_IGN  and  that  the 
process  signal  mask  be  unchanged  across  an  exec .  This  is  consistent  with  histori¬ 
cal  implementations,  and  it  permits  some  useful  functionality,  such  as  the  nohup 
command.  However,  it  should  be  noted  that  many  existing  applications  wrongly 
assume  that  they  start  with  certain  signals  set  to  the  default  action  and/or 
unblocked.  In  particular,  applications  written  with  a  simpler  signal  model  that 
does  not  include  blocking  of  signals,  such  as  the  one  in  the  C  Standard  {2},  may 
not  behave  properly  if  invoked  with  some  signals  blocked.  Therefore,  it  is  best  not 
to  block  or  ignore  signals  across  execs  without  explicit  reason  to  do  so,  and  espe¬ 
cially  not  to  block  signals  across  execs  of  arbitrary  (not  closely  co-operating) 
programs. 

If  {_POSIX_SAVED_IDS}  is  defined,  the  exec  functions  always  save  the  value  of  the 
effective  user  ID  and  effective  group  ID  of  the  process  at  the  completion  of  the 
exec,  whether  or  not  the  set-user-ID  or  the  set-group-ID  bit  of  the  process  image 
file  is  set. 

The  statement  about  argv[  \  and  envpi  ]  being  constants  is  included  to  make  expli¬ 
cit  to  future  writers  of  language  bindings  that  these  objects  are  completely  con¬ 
stant.  Due  to  a  limitation  of  the  C  Standard  {2},  it  is  not  possible  to  state  that 
idea  in  Standard  C.  Specifying  two  levels  of  const-qualification  for  the  argv[ ] 
and  envp  [  ]  parameters  for  the  exec  functions  may  seem  to  be  the  natural  choice, 
given  that  these  functions  do  not  modify  either  the  array  of  pointers  or  the  charac¬ 
ters  to  which  the  function  points,  but  this  would  disallow  existing  correct  code. 
Instead,  only  the  array  of  pointers  is  noted  as  constant.  The  table  of  assignment 
compatibility  for  dst  =  src,  derived  from  the  C  Standard  {2},  summarizes  the 
compatibility: 


dst: 

const  char  const 

char  * [ ]  char* [ ]  *const [  ]  char*const [ ] 

src : 

char  *  [  ]  VALID 

const  char  * [ ]  VALID 

char  *  const  [  ] 
const  char  *const  [  ] 

Since  all  existing  code  has  a  source  type  matching  the  first  row,  the  column  that 
gives  the  most  valid  combinations  is  the  third  column.  The  only  other  possibility 
is  the  fourth  column,  but  using  it  would  require  a  cast  on  the  argv  or  envp  argu¬ 
ments.  It  is  unfortunate  that  the  fourth  column  cannot  be  used,  because  the 
declaration  a  nonexpert  would  naturally  use  would  be  that  in  the  second  row. 

The  C  Standard  {2}  and  POSIX.1  do  not  conflict  on  the  use  of  environ,  but  some 
historical  implementations  of  environ  may  cause  a  conflict.  As  long  as  environ  is 
treated  in  the  same  way  as  an  entry  point  [e.g.,  fork() ],  it  conforms  to  both  stan¬ 
dards.  A  library  can  contain  fork(),  but  if  there  is  a  user-provided  fork 0,  that 
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1914  fork ()  is  given  precedence  and  no  problem  ensues.  The  situation  is  similar  for  | 

1915  environ — the  POSIX.l  definition  is  to  be  used  if  there  is  no  user-provided  environ  | 

1916  to  take  precedence.  At  least  three  implementations  are  known  to  exist  that  solve  | 

1917  this  problem. 

1918  [E2BIG]  The  limit  {ARG_MAX}  applies  not  just  to  the  size  of  the  argu- 

1919  ment  fist,  but  to  the  sum  of  that  and  the  size  of  the  environ- 

1920  ment  list. 


1921 

1922 

1923 


[EFAULT]  Some  historical  systems  return  [EFAULTj  rather  than  | 
[ENOEXEC1  when  the  new  process  image  file  is  corrupted.  They 
are  nonconforming. 


1924  [ENAMETOOLONG] 

1925  Since  the  file  pathname  may  be  constructed  by  taking  elements 

1926  in  the  PATH  variable  and  putting  them  together  with  the 

1927  filename,  the  [ENAMETOOLONG]  condition  could  also  be 

1928  reached  this  way. 

1929  [ETXTBSY]  The  error  [ETXTBSY]  was  considered  too  implementation 

1930  dependent  to  include.  System  V  returns  this  error  when  the 

1931  executable  file  is  currently  open  for  writing  by  some  process. 

1932  POSIX.l  neither  requires  nor  prohibits  this  behavior. 

1933  Other  systems  (such  as  System  V)  may  return  [EINTR]  from  exec .  This  is  not 

1934  addressed  by  POSIX.l,  but  implementations  may  have  a  window  between  the  call 

1935  to  exec  and  the  time  that  a  signal  could  cause  one  of  the  exec  calls  to  return  with 

1936  [EINTR]. 


1937  B.3.2  Process  Termination 

1938  Early  drafts  drew  a  different  distinction  between  normal  and  abnormal  process  | 

1939  termination.  Abnormal  termination  was  caused  only  by  certain  signals  and 

1940  resulted  in  implementation-defined  “actions,”  as  discussed  below.  Subsequent 

1941  drafts  of  POSIX.l  distinguished  three  types  of  termination:  normal  termination 

1942  (as  in  the  current  POSIX.1),  “simple  abnormal  termination,”  and  “abnormal  termi- 

1943  nation  with  actions.”  Again  the  distinction  between  the  two  types  of  abnormal 

1944  termination  was  that  they  were  caused  by  different  signals  and  that 

1945  implementation-defined  actions  would  result  in  the  latter  case.  Given  that  these 

1946  actions  were  completely  implementation  defined,  the  early  drafts  were  only  saying 

1947  when  the  actions  could  occur  and  how  their  occurrence  could  be  detected,  but  not 

1948  what  they  were.  This  was  of  little  or  no  use  to  portable  applications,  and  thus  the 

1949  distinction  was  dropped  from  POSIX.l. 

1950  The  implementation-defined  actions  usually  include,  in  most  historical  implemen- 

1951  tations,  the  creation  of  a  file  named  core  in  the  current  working  directory  of  the 

1952  process.  This  file  contains  an  image  of  the  memory  of  the  process,  together  with 

1953  descriptive  information  about  the  process,  perhaps  sufficient  to  reconstruct  the 

1954  state  of  the  process  at  the  receipt  of  the  signal. 

1955  There  is  a  potential  security  problem  in  creating  a  core  file  if  the  process  was 

1956  set-user-ID  and  the  current  user  is  not  the  owner  of  the  program,  if  the  process 

1957  was  set-group-ID  and  none  of  the  user’s  groups  match  the  group  of  the  program, 
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or  if  the  user  does  not  have  permission  to  write  in  the  current  directory.  In  this 
situation,  an  implementation  either  should  not  create  a  core  file  or  should  make 
it  unreadable  by  the  user. 

Despite  the  silence  of  POSIX.l  on  this  feature,  applications  are  advised  not  to 
create  files  named  core  because  of  potential  conflicts  in  many  implementations. 
Some  historical  implementations  use  a  different  name  than  core  for  the  file,  such 
as  by  appending  the  process  ID  to  the  filename. 

B.3.2.1  Wait  for  Process  Termination 

A  call  to  the  waitO  or  waitpid ()  function  only  returns  status  on  an  immediate 
child  process  of  the  calling  process;  i.e.,  a  child  that  was  produced  by  a  single 
forkO  call  (perhaps  followed  by  an  exec  or  other  function  calls)  from  the  parent.  If 
a  child  produces  grandchildren  by  further  use  of  forkO,  none  of  those  grandchil¬ 
dren  nor  any  of  their  descendants  will  affect  the  behavior  of  a  wait ()  from  the  ori¬ 
ginal  parent  process.  Nothing  in  POSIX.1  prevents  an  implementation  from  pro¬ 
viding  extensions  that  permit  a  process  to  get  status  from  a  grandchild  or  any 
other  process,  but  a  process  that  does  not  use  such  extensions  must  be  guaranteed 
to  see  status  from  only  its  direct  children. 

The  waitpidO  function  is  provided  for  three  reasons: 

—  To  support  job  control  (see  B.3.3). 

—  To  permit  a  nonblocking  version  of  the  wait( )  function. 

—  To  permit  a  library  routine,  such  as  systemO  or  pclose (),  to  wait  for  its  chil¬ 
dren  without  interfering  with  other  terminated  children  for  which  the  pro¬ 
cess  has  not  waited. 

The  first  two  of  these  facilities  are  based  on  the  wait3{ )  function  provided  by 
4.3BSD.  The  interface  uses  the  options  argument,  which  is  identical  to  an  argu¬ 
ment  to  wait3().  The  WUNTRACED  flag  is  used  only  in  conjunction  with  job  con¬ 
trol  on  systems  supporting  that  option.  Its  name  comes  from  4.3BSD  and  refers  to 
the  fact  that  there  are  two  types  of  stopped  processes  in  that  implementation: 
processes  being  traced  via  the  p trace  ()  debugging  facility  and  (untraced)  processes 
stopped  by  job-control  signals.  Since  ptrace ()  is  not  part  of  POSIX.l,  only  the 
second  type  is  relevant.  The  name  WUNTRACED  was  retained  because  its  usage  | 
is  the  same,  even  though  the  name  is  not  intuitively  meaningful  in  this  context. 

The  third  reason  for  the  waitpidO  function  is  to  permit  independent  sections  of  a 
process  to  spawn  and  wait  for  children  without  interfering  with  each  other.  For 
example,  the  following  problem  occurs  in  developing  a  portable  shell,  or  command  | 
interpreter: 

stream  =  popen ("/bin/true") ; 

(void)  system ( "sleep  100"); 

(void)  pclose (stream) ; 

On  all  historical  implementations,  the  final  pclose ()  will  fail  to  reap  the  wait 
status  of  the  popenO- 

The  status  values  are  retrieved  by  macros,  rather  than  given  as  specific  bit  encod¬ 
ings  as  they  are  in  most  historical  implementations  (and  thus  expected  by 
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2001  existing  programs).  This  was  necessary  to  eliminate  a  limitation  on  the  number 

2002  of  signals  an  implementation  can  support  that  was  inherent  in  the  traditional 

2003  encodings.  POSIX.1  does  require  that  a  status  value  of  zero  corresponds  to  a  pro- 

2004  cess  calling  jexitiO),  as  this  is  the  most  common  encoding  expected  by  existing 

2005  programs.  Some  of  the  macro  names  were  adopted  from  4.3BSD. 

2006  These  macros  syntactically  operate  on  an  arbitrary  integer  value.  The  behavior  is 

2007  undefined  unless  that  value  is  one  stored  by  a  successful  call  to  waiti)  or  wait- 

2008  pid( )  in  the  location  pointed  to  by  the  stat_loc  argument.  An  earlier  draft 

2009  attempted  to  make  this  clearer  by  specifying  each  argument  as  *stat_loc  rather 

2010  than  statjual.  However,  that  did  not  follow  the  conventions  of  other  specifications 

2011  in  POSIX.1  or  traditional  usage.  It  also  could  have  implied  that  the  argument  to 

2012  the  macro  must  literally  be  *stat_loc;  in  fact,  that  value  can  be  stored  or  passed  as 

2013  an  argument  to  other  functions  before  being  interpreted  by  these  macros. 

2014  The  extension  that  affects  waiti )  and  waitpidO  and  is  common  in  historical  imple- 

2015  mentations  is  the  ptrace  ()  function.  It  is  called  by  a  child  process  and  causes  that 

2016  child  to  stop  and  return  a  status  that  appears  identical  to  the  status  indicated  by 

2017  WIFSTOPPED.  The  status  of  ptraced  children  is  traditionally  returned  regardless 

2018  of  the  WUNTRACED  flag  [or  by  the  wait{)  function].  Most  applications  do  not  need 

2019  to  concern  themselves  with  such  extensions  because  they  have  control  over  what 

2020  extensions  they  or  their  children  use.  However,  applications,  such  as  command 

2021  interpreters,  that  invoke  arbitrary  processes  may  see  this  behavior  when  those 

2022  arbitrary  processes  misuse  such  extensions. 

2023  Implementations  that  support  core  file  creation  or  other  implementation-defined 

2024  actions  on  termination  of  some  processes  traditionally  provide  a  bit  in  the  status 

2025  returned  by  waiti )  to  indicate  that  such  actions  have  occurred. 

2026  B.3.2.2  Terminate  a  Process 

2027  Most  C  language  programs  should  use  the  exit ()  function  rather  than  jexiti).  The 

2028  jexiti )  function  is  defined  here  instead  of  ex iti )  because  the  C  Standard  {2}  defines 

2029  the  latter  to  have  certain  characteristics  that  are  beyond  the  scope  of  POSIX.1, 

2030  specifically  the  flushing  of  buffers  on  open  files  and  the  use  of  atexiti).  See  “The  C  | 

2031  Language”  in  the  Introduction.  There  are  several  public-domain  implementations  | 

2032  of  atexiti )  that  may  be  of  use  to  interface  implementors  who  wish  to  incorporate  it. 

2033  It  is  important  that  the  consequences  of  process  termination  as  described  in  this 

2034  subclause  occur  regardless  of  whether  the  process  called  _exit()  [perhaps  | 

2035  indirectly  through  exiti)]  or  instead  was  terminated  due  to  a  signal  or  for  some 

2036  other  reason.  Note  that  in  the  specific  case  of  exiti)  this  means  that  the  status 

2037  argument  to  exiti)  is  treated  the  same  as  the  status  argument  to  jexiti).  See  also 

2038  B.3.2. 

2039  A  language  other  than  C  may  have  other  termination  primitives  than  the  C 

2040  language  exiti )  function,  and  programs  written  in  such  a  language  should  use  its 

2041  native  termination  primitives,  but  those  should  have  as  part  of  their  function  the 

2042  behavior  of  jexiti )  as  described  in  this  subclause.  Implementations  in  languages  | 

2043  other  than  C  are  outside  the  scope  of  the  present  version  of  POSIX.1,  however. 

2044  As  required  by  the  C  Standard  {2},  using  return  from  maini)  is  equivalent  to  cal-  | 

2045  ling  exiti)  with  the  same  argument  value.  Also,  reaching  the  end  of  the  maini) 


232 


B  Rationale  and  Notes 


2046 

2047 

2048 

2049 

2050 

2051 

2052 

2053 

2054 

2055 

2056 

2057 

2058 

2059 

2060 

2061 

2062 

2063 

2064 

2065 

2066 

2067 

2068 

2069 

2070 

2071 

2072 

2073 

2074 

2075 

2076 

2077 

2078 

2079 

2080 

2081 

2082 

2083 

2084 

2085 

2086 

2087 

2088 

2089 

2090 

2091 

2092 


Part  1:  SYSTEM  API  [C  LANGUAGE] 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


function  is  equivalent  to  using  exit{ )  with  an  unspecified  value. 

A  value  of  zero  (or  EXIT_SUCCESS,  which  is  required  by  8.1  to  be  zero)  for  the  | 
argument  status  conventionally  indicates  successful  termination.  This 
corresponds  to  the  specification  for  exit()  in  the  C  Standard  {2}.  The  convention  is 
followed  by  utilities  such  as  make  and  various  shells,  which  interpret  a  zero 
status  from  a  child  process  as  success.  For  this  reason,  applications  should  not 
call  exit(0 )  or  jexit(O)  when  they  terminate  unsuccessfully,  for  example  in  signal- 
catching  functions. 

Historically,  the  implementation-dependent  process  that  inherits  children  whose 
parents  have  terminated  without  waiting  on  them  is  called  in  it  and  has  a  pro¬ 
cess  ID  of  1. 

The  sending  of  a  SIGHUP  to  the  foreground  process  group  when  a  controlling  pro¬ 
cess  terminates  corresponds  to  somewhat  different  historical  implementations.  In  | 
System  V,  the  kernel  sends  a  SIGHUP  on  termination  of  (essentially)  a  controlling 
process.  In  4.2BSD,  the  kernel  does  not  send  SIGHUP  in  a  case  like  this,  but  the 
termination  of  a  controlling  process  is  usually  noticed  by  a  system  daemon,  which 
arranges  to  send  a  SIGHUP  to  the  foreground  process  group  with  the  v hangup  () 
function.  However,  in  4.2BSD,  due  to  the  behavior  of  the  shells  that  support  job 
control,  the  controlling  process  is  usually  a  shell  with  no  other  processes  in  its 
process  group.  Thus,  a  change  to  make  _ex it{)  behave  this  way  in  such  systems 
should  not  cause  problems  with  existing  applications. 

The  termination  of  a  process  may  cause  a  process  group  to  become  orphaned  in 
either  of  two  ways.  The  connection  of  a  process  group  to  its  parent(s)  outside  of 
the  group  depends  on  both  the  parents  and  their  children.  Thus,  a  process  group 
may  be  orphaned  by  the  termination  of  the  last  connecting  parent  process  outside 
of  the  group  or  by  the  termination  of  the  last  direct  descendant  of  the  parent 
process(es).  In  either  case,  if  the  termination  of  a  process  causes  a  process  group 
to  become  orphaned,  processes  within  the  group  are  disconnected  from  their  job 
control  shell,  which  no  longer  has  any  information  on  the  existence  of  the  process 
group.  Stopped  processes  within  the  group  would  languish  forever.  In  order  to 
avoid  this  problem,  newly  orphaned  process  groups  that  contain  stopped  processes 
are  sent  a  SIGHUP  signal  and  a  SIGCONT  signal  to  indicate  that  they  have  been 
disconnected  from  their  session.  The  SIGHUP  signal  causes  the  process  group 
members  to  terminate  unless  they  are  catching  or  ignoring  SIGHUP.  Under  most 
circumstances,  all  of  the  members  of  the  process  group  are  stopped  if  any  of  them 
are  stopped. 

The  action  of  sending  a  SIGHUP  and  a  SIGCONT  signal  to  members  of  a  newly 
orphaned  process  group  is  similar  to  the  action  of  4.2BSD,  which  sends  SIGHUP 
and  SIGCONT  to  each  stopped  child  of  an  exiting  process.  If  such  children  exit  in 
response  to  the  SIGHUP,  any  additional  descendants  will  receive  similar  treat¬ 
ment  at  that  time.  In  POSIX.l,  the  signals  will  be  sent  to  the  entire  process  group 
at  the  same  time.  Also,  in  POSIX.1,  but  not  in  4.2BSD,  stopped  processes  may  be 
orphaned,  but  may  be  members  of  a  process  group  that  is  not  orphaned;  therefore, 
the  action  taken  at  _exit()  must  consider  processes  other  than  child  processes. 

It  is  possible  for  a  process  group  to  be  orphaned  by  a  call  to  setpgidi)  or  setsidO,  \ 
as  well  as  by  process  termination.  POSIX.1  does  not  require  sending  SIGHUP  and  | 
SIGCONT  in  those  cases,  because,  unlike  process  termination,  those  cases  will  not  | 
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be  caused  accidentally  by  applications  that  are  unaware  of  job  control.  An  imple-  | 
mentation  can  choose  to  send  SIGHUP  and  SIGCONT  in  those  cases  as  an  exten-  | 
sion;  such  an  extension  must  be  documented  as  required  in  3.3. 1.2. 


B.3.3  Signals 

Signals,  as  defined  in  Version  7,  System  III,  the  1984  /usr /group  Standard  {B59},  | 

and  System  V  (except  very  recent  releases),  have  shortcomings  that  make  them  | 
unreliable  for  many  application  uses.  Several  objections  were  raised  against  early  | 
drafts  of  POSIX.  1  because  of  this.  Therefore,  a  new  signal  mechanism,  based  very  | 
closely  on  the  one  of  4.2BSD  and  4.3BSD,  was  added  to  POSIX.1.  With  the  excep¬ 
tion  of  one  feature  [see  item  (4)  below  and  also  sigpending ()],  it  is  possible  to 
implement  the  POSIX.1  interface  as  a  simple  library  veneer  on  top  of  4.3BSD. 
There  are  also  a  few  minor  aspects  of  the  underlying  4.3BSD  implementation  (as 
opposed  to  the  interface)  that  would  also  need  to  change  to  conform  to  POSIX.1. 

The  major  differences  from  the  BSD  mechanism  are: 

(1)  Signal  mask  type.  BSD  uses  the  type  int  to  represent  a  signal  mask,  thus 
limiting  the  number  of  signals  to  the  number  of  bits  in  an  int  (typically 
32).  The  new  standard  instead  uses  a  defined  type  for  signal  masks. 
Because  of  this  change,  the  interface  is  significantly  different  than  it  is  in 
BSD  implementations,  although  the  functionality,  and  potentially  the 
implementation,  are  very  similar. 

(2)  Restarting  system  calls.  Unlike  all  previous  historical  implementations, 
4.2BSD  restarts  some  interrupted  system  calls  rather  than  returning  an 
error  with  errno  set  to  [EINTR]  after  the  signal-catching  function  returns. 
This  change  caused  problems  for  some  existing  application  code.  4.3BSD 
and  other  systems  derived  from  4.2BSD  allow  the  application  to  choose 
whether  system  calls  are  to  be  restarted.  POSIX.1  (in  3.3.4)  does  not 
require  restart  of  functions  because  it  was  not  clear  that  the  semantics  of 
system-call  restart  in  any  historical  implementation  were  useful  enough  | 
to  be  of  value  in  a  standard.  Implementors  are  free  to  add  such  mechan¬ 
isms  as  extensions. 

(3)  Signal  stacks.  The  4.2BSD  mechanism  includes  a  function  sigstack (). 
The  4.3BSD  mechanism  includes  this  and  a  function  sigreturn().  No 
equivalent  is  included  in  POSIX.1  because  these  functions  are  not  port¬ 
able,  and  no  sufficiently  portable  and  useful  equivalent  has  been 
identified.  See  also  8.3.1. 

(4)  Pending  signals.  The  sigpendingi)  function  is  the  sole  new  signal  opera-  | 

tion  introduced  in  POSIX.1.  I 

A  proposal  was  considered  for  making  reliable  signals  optional.  However,  the  | 
consensus  was  that  this  would  hurt  application  portability,  as  a  large  percentage 
of  applications  using  signals  can  be  hurt  by  the  unreliable  aspects  of  historical 
implementations  of  the  signali)  mechanism  defined  by  the  C  Standard  {2}.  This 
unreliability  stems  from  the  fact  that  the  signal  action  is  reset  to  SIG_DFL  before 
the  user’s  signal -catching  routine  is  entered.  The  C  Standard  {2}  does  not  require 
this  behavior,  but  does  explicitly  permit  it,  and  most  historical  implementations  | 
behave  this  way.  I 
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For  example,  an  application  that  catches  the  SIGINT  signal  using  signalO  could 
be  terminated  with  no  chance  to  recover  when  two  such  signals  arrive  sufficiently 
close  in  time  (e.g.,  when  an  impatient  user  types  the  INTR  character  twice  in  a 
row  on  a  busy  system).  Although  the  C  Standard  {2}  no  longer  requires  this 
unreliable  behavior,  many  historical  implementations,  including  System  V,  will  | 
reset  the  signal  action  to  SIG_DFL.  For  this  reason,  it  is  strongly  recommended 
that  the  signalO  function  not  be  used  by  POSIX.1  conforming  applications.  Imple¬ 
mentations  should  also  consider  blocking  signals  during  the  execution  of  the 
signal-catching  function  instead  of  resetting  the  action  to  SIG_DFL,  but  backward 
compatibility  considerations  will  most  likely  prevent  this  from  becoming 
universal. 

Most  historical  implementations  do  not  queue  signals;  i.e.,  a  process’s  signal 
handler  is  invoked  once,  even  if  the  signal  has  been  generated  multiple  times 
before  it  is  delivered.  A  notable  exception  to  this  is  SIGCLD,  which,  in  System  V, 
is  queued.  The  queueing  of  signals  is  neither  required  nor  prohibited  by  POSIX.1.  | 
See  3. 3. 1.2.  It  is  expected  that  a  future  realtime  extension  to  POSIX.1  will  address  j 
the  issue  of  reliable  queueing  of  event  notification. 

B.3.3.1  Signal  Concepts 
B.3.3.1.1  Signal  Names 

The  restriction  on  the  actual  type  used  for  sigsetjt  is  intended  to  guarantee  that 
these  objects  can  always  be  assigned,  have  their  address  taken,  and  be  passed  as 
parameters  by  value.  It  is  not  intended  that  this  type  be  a  structure  including 
pointers  to  other  data  structures,  as  that  could  impact  the  portability  of  applica¬ 
tions  performing  such  operations.  A  reasonable  implementation  could  be  a  struc¬ 
ture  containing  an  array  of  some  integer  type. 

The  signals  described  in  POSIX.1  must  have  unique  values  so  that  they  may  be 
named  as  parameters  of  case  statements  in  the  body  of  a  C  language  switch 
clause.  However,  implementation-defined  signals  may  have  values  that  overlap 
with  each  other  or  with  signals  specified  in  this  document.  An  example  of  this  is 
SIGABRT,  which  traditionally  overlaps  some  other  signal,  such  as  SIGIOT. 

SIGKILL,  SIGTERM,  SIGUSR1,  and  SIGUSR2  are  ordinarily  generated  only  through 
the  explicit  use  of  the  killO  function,  although  some  implementations  generate 
SIGKILL  under  extraordinary  circumstances.  SIGTERM  is  traditionally  the 
default  signal  sent  by  the  kill  command. 

The  signals  SIGBUS,  SIGEMT,  SIGIOT,  SIGTRAP,  and  SIGSYS  were  omitted  from 
POSIX.1  because  their  behavior  is  implementation  dependent  and  could  not  be 
adequately  categorized.  Conforming  implementations  may  deliver  these  signals, 
but  must  document  the  circumstances  under  which  they  are  delivered  and  note 
any  restrictions  concerning  their  delivery.  The  signals  SIGFPE,  SIGILL,  and  SIG- 
SEGV  are  similar  in  that  they  also  generally  result  only  from  programming  errors. 
They  were  included  in  POSIX.1  because  they  do  indicate  three  relatively  well- 
categorized  conditions.  They  are  all  defined  by  the  C  Standard  {2}  and  thus  would 
have  to  be  defined  by  any  system  with  a  C  Standard  {2}  binding,  even  if  not  expli¬ 
citly  included  in  POSIX.1. 
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There  is  very  little  that  a  Conforming  POSIX.  1  Application  can  do  by  catching, 
ignoring,  or  masking  any  of  the  signals  SIGILL,  SIGTRAP,  SIGIOT,  SIGEMT, 
SIGBUS,  SIGSEGV,  SIGSYS,  or  SIGFPE.  They  will  generally  be  generated  by  the 
system  only  in  cases  of  programming  errors.  While  it  may  be  desirable  for  some 
robust  code  (e.g.,  a  library  routine)  to  be  able  to  detect  and  recover  from  program¬ 
ming  errors  in  other  code,  these  signals  are  not  nearly  sufficient  for  that  purpose. 
One  portable  use  that  does  exist  for  these  signals  is  that  a  command  interpreter 
can  recognize  them  as  the  cause  of  a  process’s  termination  [with  wait() ]  and  print 
an  appropriate  message.  The  mnemonic  tags  for  these  signals  are  derived  from 
their  PDP-11  origin. 

The  signals  SIGSTOP,  SIGTSTP,  SIGTTIN,  SIGTTOU,  and  SIGCONT  are  provided  for 
job  control  and  are  unchanged  from  4.2BSD.  The  signal  SIGCHLD  is  also  typically 
used  by  job  control  shells  to  detect  children  that  have  terminated  or,  as  in  4.2BSD, 
stopped.  See  also  B.3.3.4. 

Some  implementations,  including  System  V,  have  a  signal  named  SIGCLD,  which 
is  similar  to  SIGCHLD  in  4.2BSD.  POSIX.  1  permits  implementations  to  have  a  sin¬ 
gle  signal  with  both  names.  POSIX.  1  carefully  specifies  ways  in  which  portable 
applications  can  avoid  the  semantic  differences  between  the  two  different  imple¬ 
mentations.  The  name  SIGCHLD  was  chosen  for  POSIX.  1  because  most  current 
application  usages  of  it  can  remain  unchanged  in  conforming  applications. 
SIGCLD  in  System  V  has  more  cases  of  semantics  that  POSIX.l  does  not  specify, 
and  thus  applications  using  it  are  more  likely  to  require  changes  in  addition  to 
the  name  change. 

Some  implementations  that  do  not  support  job  control  may  nonetheless  imple¬ 
ment  SIGCHLD.  Similarly,  such  an  implementation  may  choose  to  implement  SIG¬ 
STOP.  Since  POSIX.l  requires  that  symbolic  names  always  be  defined  (with  the 
exception  of  certain  names  in  <limits  .h>  and  <unistd.h>),  a  portable  method 
of  determining,  at  run-time,  whether  an  optional  signal  is  supported  is  to  call  the 
sigactionO  function  with  NULL  act  and  oact  arguments.  A  successful  return  indi¬ 
cates  that  the  signal  is  supported.  Note  that  if  syscon/X )  shows  that  job  control  is 
present,  then  all  of  the  optional  signals  shall  also  be  supported. 

The  signals  SIGUSR1  and  SIGUSR2  are  commonly  used  by  applications  for 
notification  of  exceptional  behavior  and  are  described  as  “reserved  as  application 
defined”  so  that  such  use  is  not  prohibited.  Implementations  should  not  generate 
SIGUSR1  or  SIGUSR2,  except  when  explicitly  requested  by  kill().  It  is  recom¬ 
mended  that  libraries  not  use  these  two  signals,  as  such  use  in  libraries  could 
interfere  with  their  use  by  applications  calling  the  libraries.  If  such  use  is  una¬ 
voidable,  it  should  be  documented.  It  is  prudent  for  nonportable  libraries  to  use 
nonstandard  signals  to  avoid  conflicts  with  use  of  standard  signals  by  portable 
libraries. 

There  is  no  portable  way  for  an  application  to  catch  or  ignore  nonstandard  sig-  | 
nals.  Some  implementations  define  the  range  of  signal  numbers,  so  applications 
can  install  signal-catching  functions  for  all  of  them.  Unfortunately, 
implementation-defined  signals  often  cause  problems  when  caught  or  ignored  by 
applications  that  do  not  understand  the  reason  for  the  signal.  While  the  desire 
exists  for  an  application  to  be  more  robust  by  handling  all  possible  signals  [even 
those  only  generated  by  kill() ],  no  existing  mechanism  was  found  to  be  sufficiently 
portable  to  include  in  POSIX.l.  The  value  of  such  a  mechanism,  if  included,  would 
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be  diminished  given  that  SIGKILL  would  still  not  be  catchable. 

B.3.3.1.2  Signal  Generation  and  Delivery 

The  terms  defined  in  this  subclause  are  not  used  consistently  in  documentation  of  | 
historical  systems.  Each  signal  can  be  considered  to  have  a  lifetime  beginning  | 
with  generation  and  ending  with  delivery.  The  POSIX.1  definition  of  delivery  does  | 
not  exclude  ignored  signals;  this  is  considered  a  more  consistent  definition. 

Implementations  should  deliver  unblocked  signals  as  soon  after  they  are  gen¬ 
erated  as  possible.  However,  it  is  difficult  for  POSIX.1  to  make  specific  require¬ 
ments  about  this,  beyond  those  in  kill{)  and  sigprocmask{).  Even  on  systems  with 
prompt  delivery,  scheduling  of  higher  priority  processes  is  always  likely  to  cause 
delays. 

In  general,  the  interval  between  the  generation  and  delivery  of  unblocked  signals 
cannot  be  detected  by  an  application.  Thus,  references  to  pending  signals  gen¬ 
erally  apply  to  blocked,  pending  signals. 

In  the  4.3BSD  system,  signals  that  are  blocked  and  set  to  SIG_IGN  are  discarded 
immediately  upon  generation.  For  a  signal  that  is  ignored  as  its  default  action,  if 
the  action  is  SIG_DFL  and  the  signal  is  blocked,  a  generated  signal  remains  pend¬ 
ing.  In  the  4.1BSD  system  and  in  System  V  Release  3,  two  other  implementations 
that  support  a  somewhat  similar  signal  mechanism,  all  ignored,  blocked  signals 
remain  pending  if  generated.  Because  it  is  not  normally  useful  for  an  application 
to  simultaneously  ignore  and  block  the  same  signal,  it  was  unnecessary  for 
POSIX.1  to  specify  behavior  that  would  invalidate  any  of  the  historical  | 
implementations.  | 

There  is  one  case  in  some  historical  implementations  where  an  unblocked,  pend-  | 
ing  signal  does  not  remain  pending  until  it  is  delivered.  In  the  System  V  imple¬ 
mentation  of  signal(),  pending  signals  are  discarded  when  the  action  is  set  to 
SIG_DFL  or  a  signal-catching  routine  (as  well  as  to  SIG_IGN).  Except  in  the  case 
of  setting  SIGCHLD  to  SIG_DFL,  implementations  that  do  this  do  not  conform  com¬ 
pletely  to  POSIX.1.  Some  earlier  drafts  of  POSIX.1  explicitly  stated  this,  but  these 
statements  were  redundant  due  to  the  requirement  that  functions  defined  by 
POSIX.1  not  change  attributes  of  processes  defined  by  POSIX.1  except  as  explicitly 
stated  (see  Section  3). 

POSIX.1  specifically  states  that  the  order  in  which  multiple,  simultaneously  pend¬ 
ing  signals  are  delivered  is  unspecified.  This  order  has  not  been  explicitly 
specified  in  historical  implementations,  but  has  remained  quite  consistent  and 
been  known  to  those  familiar  with  the  implementations.  Thus,  there  have  been 
cases  where  applications  (usually  system  utilities)  have  been  written  with  explicit 
or  implicit  dependencies  on  this  order.  Implementors  and  others  porting  existing 
applications  may  need  to  be  aware  of  such  dependencies. 

When  there  are  multiple  pending  signals  that  are  not  blocked,  implementations 
should  arrange  for  the  delivery  of  all  signals  at  once,  if  possible.  Some  implemen¬ 
tations  stack  calls  to  all  pending  signal-catching  routines,  making  it  appear  that 
each  signal-catcher  was  interrupted  by  the  next  signal.  In  this  case,  the  imple¬ 
mentation  should  ensure  that  this  stacking  of  signals  does  not  violate  the  seman¬ 
tics  of  the  signal  masks  established  by  sigactioni).  Other  implementations  pro¬ 
cess  at  most  one  signal  when  the  operating  system  is  entered,  with  remaining 
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signals  saved  for  later  delivery.  Although  this  practice  is  widespread,  this  | 
behavior  is  neither  standardized  nor  endorsed.  In  either  case,  implementations  | 
should  attempt  to  deliver  signals  associated  with  the  current  state  of  the  process 
(e.g.,  SIGFPE)  before  other  signals,  if  possible. 

In  4.2BSD  and  4.3BSD,  it  is  not  permissible  to  ignore  or  explicitly  block  SIGCONT 
because  if  blocking  or  ignoring  this  signal  prevented  it  from  continuing  a  stopped 
process,  such  a  process  could  never  be  continued  (only  killed  by  SIGKILL).  How¬ 
ever,  4.2BSD  and  4.3BSD  do  block  SIGCONT  during  execution  of  its  signal-catching 
function  when  it  is  caught,  creating  exactly  this  problem.  A  proposal  was  con-  | 
sidered  to  disallow  catching  SIGCONT  in  addition  to  ignoring  and  blocking  it,  but  | 
this  limitation  led  to  objections.  The  consensus  was  to  require  that  SIGCONT 
always  continue  a  stopped  process  when  generated.  This  removed  the  need  to 
disallow  ignoring  or  explicit  blocking  of  the  signal;  note  that  SIG_IGN  and 
SIG_DFL  are  equivalent  for  SIGCONT. 

B.3.3.1.3  Signal  Actions 

Earlier  drafts  of  POSIX.1  mentioned  SIGCONT  as  a  second  exception  to  the  rule 
that  signals  are  not  delivered  to  stopped  processes  until  continued.  Because 
POSIX.1  now  specifies  that  SIGCONT  causes  the  stopped  process  to  continue  when 
it  is  generated,  delivery  of  SIGCONT  is  not  prevented  because  a  process  is  stopped, 
even  without  an  explicit  exception  to  this  rule. 

Ignoring  a  signal  by  setting  the  action  to  SIG_IGN  (or  SIG_DFL  for  signals  whose 
default  action  is  to  ignore)  is  not  the  same  as  installing  a  signal-catching  function 
that  simply  returns.  Invoking  such  a  function  will  interrupt  certain  system  func¬ 
tions  that  block  processes  [e.g.,  wait (),  sigsuspend (),  pause (),  read(),  write ()] 
while  ignoring  a  signal  has  no  such  effect  on  the  process. 

Historical  implementations  discard  pending  signals  when  the  action  is  set  to 
SIG_IGN.  However,  they  do  not  always  do  the  same  when  the  action  is  set  to 
SIG_DFL  and  the  default  action  is  to  ignore  the  signal.  POSIX.1  requires  this  for 
the  sake  of  consistency  and  also  for  completeness,  since  the  only  signal  this 
applies  to  is  SIGCHLD,  and  POSIX.1  disallows  setting  its  action  to  SIG_IGN. 

The  specification  of  the  effects  of  SIG_IGN  on  SIGCHLD  as  implementation  defined 
permits,  but  does  not  require,  the  System  V  effect  of  causing  terminating  children 
to  be  ignored  by  wait().  Yet  it  permits  SIGCHLD  to  be  effectively  ignored  in  an 
implementation-independent  manner  by  use  of  SIG_DFL. 

Some  implementations  (System  V,  for  example)  assign  different  semantics  for 
SIGCLD  depending  on  whether  the  action  is  set  to  SIG_IGN  or  SIG_DFL.  Since 
POSIX.1  requires  that  the  default  action  for  SIGCHLD  be  to  ignore  the  signal, 
applications  should  always  set  the  action  to  SIG_DFL  in  order  to  avoid  SIGCHLD. 

Some  implementations  (System  V,  for  example)  will  deliver  a  SIGCLD  signal 
immediately  when  a  process  establishes  a  signal-catching  function  for  SIGCLD 
when  that  process  has  a  child  that  has  already  terminated.  Other  implementa¬ 
tions,  such  as  4.3BSD,  do  not  generate  a  new  SIGCHLD  signal  in  this  way.  In  gen¬ 
eral,  a  process  should  not  attempt  to  alter  the  signal  action  for  the  SIGCHLD  sig¬ 
nal  while  it  has  any  outstanding  children.  However,  it  is  not  always  possible  for  a 
process  to  avoid  this;  for  example,  shells  sometimes  start  up  processes  in  pipe¬ 
lines  with  other  processes  from  the  pipeline  as  children.  Processes  that  cannot 
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ensure  that  they  have  no  children  when  altering  the  signal  action  for  SIGCHLD 
thus  need  to  be  prepared  for,  but  not  depend  on,  generation  of  an  immediate 
SIGCHLD  signal. 

The  default  action  of  the  stop  signals  (SIGSTOP,  SIGTSTP,  SIGTTIN,  SIGTTOU)  is 
to  stop  a  process  that  is  executing.  If  a  stop  signal  is  delivered  to  a  process  that  is 
already  stopped,  it  has  no  effect.  In  fact,  if  a  stop  signal  is  generated  for  a 
stopped  process  whose  signal  mask  blocks  the  signal,  the  signal  will  never  be 
delivered  to  the  process  since  the  process  must  receive  a  SIGCONT,  which  discards 
all  pending  stop  signals,  in  order  to  continue  executing. 

The  SIGCONT  signal  shall  continue  a  stopped  process  even  if  SIGCONT  is  blocked 
(or  ignored).  However,  if  a  signal-catching  routine  has  been  established  for 
SIGCONT,  it  will  not  be  entered  until  SIGCONT  is  unblocked. 

If  a  process  in  an  orphaned  process  group  stops,  it  is  no  longer  under  the  control 
of  a  job-control  shell  and  hence  would  not  normally  ever  be  continued.  Because  of 
this,  orphaned  processes  that  receive  terminal-related  stop  signals  (SIGTSTP, 
SIGTTIN,  SIGTTOU,  but  not  SIGSTOP)  must  not  be  allowed  to  stop.  The  goal  is  to 
prevent  stopped  processes  from  languishing  forever.  [As  SIGSTOP  is  sent  only  via 
kill( ),  it  is  assumed  that  the  process  or  user  sending  a  SIGSTOP  can  send  a 
SIGCONT  when  desired.]  Instead,  the  system  must  discard  the  stop  signal.  As  an 
extension,  it  may  also  deliver  another  signal  in  its  place.  4.3BSD  sends  a  SIG- 
KILL,  which  is  overly  effective  because  SIGKILL  is  not  catchable.  Another  possible 
choice  is  SIGHUP.  4.3BSD  also  does  this  for  orphaned  processes  (processes  whose 
parent  has  terminated)  rather  than  for  members  of  orphaned  process  groups;  this 
is  less  desirable  because  job-control  shells  manage  process  groups.  POSIX.l  also 
prevents  SIGTTIN  and  SIGTTOU  signals  from  being  generated  for  processes  in 
orphaned  process  groups  as  a  direct  result  of  activity  on  a  terminal,  preventing 
infinite  loops  when  read{)  and  write ()  calls  generate  signals  that  are  discarded. 
(See  B.7. 1.1.4.)  A  similar  restriction  on  the  generation  of  SIGTSTP  was  con-  | 
sidered,  but  that  would  be  unnecessary  and  more  difficult  to  implement  due  to  its 
asynchronous  nature. 

Although  POSIX.1  requires  that  signal-catching  functions  be  called  with  only  one 
argument,  there  is  nothing  to  prevent  conforming  implementations  from  extend¬ 
ing  POSIX.1  to  pass  additional  arguments,  as  long  as  Strictly  Conforming  POSIX.l 
Applications  continue  to  compile  and  execute  correctly.  Most  historical  implemen¬ 
tations  do,  in  fact,  pass  additional,  signal-specific  arguments  to  certain  signal- 
catching  routines. 

There  was  a  proposal  to  change  the  declared  type  of  the  signal  handler  to: 
void  func  (int  sig,  ...  )  ; 

The  usage  of  ellipses  (“,  . . .  ”)  is  C  Standard  {2}  syntax  to  indicate  a  variable 
number  of  arguments.  Its  use  was  intended  to  allow  the  implementation  to  pass 
additional  information  to  the  signal  handler  in  a  standard  manner. 

Unfortunately,  this  construct  would  require  all  signal  handlers  to  be  defined  with 
this  syntax  because  the  C  Standard  {2}  allows  implementations  to  use  a  different 
parameter  passing  mechanism  for  variable  parameter  lists  than  for  nonvariable 
parameter  lists.  Thus,  all  existing  signal  handlers  in  all  existing  applications 
would  have  to  be  changed  to  use  the  variable  syntax  in  order  to  be  standard  and 
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portable.  This  is  in  conflict  with  the  goal  of  Minimal  Changes  to  Existing  Applica¬ 
tion  Code. 

When  terminating  a  process  from  a  signal-catching  function,  processes  should  be 
aware  of  any  interpretation  that  their  parent  may  make  of  the  status  returned  by 
waitO  or  waitpid ().  In  particular,  a  signal-catching  function  should  not  call 
exit(0)  or  _exit( 0)  unless  it  wants  to  indicate  successful  termination.  A  nonzero 
argument  to  exitO  or  jexitO  can  be  used  to  indicate  unsuccessful  termination. 
Alternatively,  the  process  can  use  killO  to  send  itself  a  fatal  signal  (first  ensuring 
that  the  signal  is  set  to  the  default  action  and  not  blocked).  (See  also  B.3.2.2). 

The  behavior  of  unsafe  functions,  as  defined  by  this  subclause,  is  undefined  when  | 
they  are  invoked  from  signal-catching  functions  in  certain  circumstances.  The  | 
behavior  of  reentrant  functions,  as  defined  by  this  subclause,  is  as  specified  by  | 
POSIX.  1,  regardless  of  invocation  from  a  signal-catching  function.  This  is  the  only 
intended  meaning  of  the  statement  that  reentrant  functions  may  be  used  in 
signal-catching  functions  without  restriction.  Applications  must  still  consider  all 
effects  of  such  functions  on  such  things  as  data  structures,  files,  and  process  state. 

In  particular,  application  writers  need  to  consider  the  restrictions  on  interactions 
when  interrupting  sleep ()  [see  sleep ()  and  B.3.4.3]  and  interactions  among  multi¬ 
ple  handles  for  a  file  description  (see  8.2.3  and  B.8.2.3).  The  fact  that  any  specific 
function  is  listed  as  reentrant  does  not  necessarily  mean  that  invocation  of  that 
function  from  a  signal-catching  function  is  recommended. 

In  order  to  prevent  errors  arising  from  interrupting  nonreentrant  function  calls, 
applications  should  protect  calls  to  these  functions  either  by  blocking  the 
appropriate  signals  or  through  the  use  of  some  programmatic  semaphore. 
POSIX.  1  does  not  address  the  more  general  problem  of  synchronizing  access  to 
shared  data  structures.  Note  in  particular  that  even  the  “safe”  functions  may 
modify  the  global  variable  errno ;  the  signal-catching  function  may  want  to  save 
and  restore  its  value.  The  same  principles  apply  to  the  reentrancy  of  application 
routines  and  asynchronous  data  access. 

Note  that  longjmpO  and  siglongjmp  ()  are  not  in  the  list  of  reentrant  functions. 
This  is  because  the  code  executing  after  longjmpO  or  siglongjmp 0  can  call  any 
unsafe  functions  with  the  same  danger  as  calling  those  unsafe  functions  directly 
from  the  signal  handler.  Applications  that  use  longjmpO  or  siglongjmp O  out  of 
signal  handlers  require  rigorous  protection  in  order  to  be  portable.  Many  of  the 
other  functions  that  are  excluded  from  the  list  are  traditionally  implemented 
using  either  the  C  language  malloc ()  or  freeO  functions  or  the  C  language  stan¬ 
dard  I/O  library,  both  of  which  traditionally  use  data  structures  in  a  nonreentrant 
manner.  Because  any  combination  of  different  functions  using  a  common  data 
structure  can  cause  reentrancy  problems,  POSIX.  1  does  not  define  the  behavior 
when  any  unsafe  function  is  called  in  a  signal  handler  that  interrupts  any  unsafe 
function. 

B.3.3.1.4  Signal  Effects  on  Other  Functions 

The  most  common  behavior  of  an  interrupted  function  after  a  signal-catching  | 
function  returns  is  for  the  interrupted  function  to  give  an  [EINTR]  error.  How¬ 
ever,  there  are  a  number  of  specific  exceptions,  including  sleep 0  and  certain 
situations  with  readO  and  write  0- 
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The  historical  implementations  of  many  functions  defined  by  POSIX.l  are  not 
interruptible,  but  delay  delivery  of  signals  generated  during  their  execution  until 
after  they  complete.  This  is  never  a  problem  for  functions  that  are  guaranteed  to 
complete  in  a  short  (imperceptible  to  a  human)  period  of  time.  It  is  normally 
those  functions  that  can  suspend  a  process  indefinitely  or  for  long  periods  of  time 
[e.g.,  wait (), pause (),  sigsuspendO,  sleepi),  or  read{)/write{)  on  a  slow  device  like  a 
terminal]  that  are  interruptible.  This  permits  applications  to  respond  to  interac¬ 
tive  signals  or  to  set  timeouts  on  calls  to  most  such  functions  with  alarm  (). 
Therefore,  implementations  should  generally  make  such  functions  (including  ones 
defined  as  extensions)  interruptible. 

Functions  not  mentioned  explicitly  as  interruptible  may  be  so  on  some  implemen¬ 
tations,  possibly  as  an  extension  where  the  function  gives  an  [EINTR]  error. 
There  are  several  functions  [e.g.,  getpid(),  getuidi) ]  that  are  specified  as  never 
returning  an  error,  which  can  thus  never  be  extended  in  this  way. 

B.3.3.2  Send  a  Signal  to  a  Process 

The  semantics  for  permission  checking  for  kill()  differ  between  System  V  and 
most  other  implementations,  such  as  Version  7  or  4.3BSD.  The  semantics  chosen 
for  POSIX.l  agree  with  System  V.  Specifically,  a  set-user-ID  process  cannot  pro¬ 
tect  itself  against  signals  (or  at  least  not  against  SIGKILL)  unless  it  changes  its 
real  user  ID.  This  choice  allows  the  user  who  starts  an  application  to  send  it  sig¬ 
nals  even  if  it  changes  its  effective  user  ID.  The  other  semantics  give  more  power 
to  an  application  that  wants  to  protect  itself  from  the  user  who  ran  it. 

Some  implementations  provide  semantic  extensions  to  the  kill{)  function  when 
the  absolute  value  of  pid  is  greater  than  some  maximum,  or  otherwise  special, 
value.  Negative  values  are  a  flag  to  kill{).  Since  most  implementations  return 
[ESRCH]  in  this  case,  this  behavior  is  not  included  in  POSIX.1,  although  a  con-  | 
forming  implementation  could  provide  such  an  extension. 

The  implementation-defined  processes  to  which  a  signal  cannot  be  sent  may 
include  the  scheduler  or  i nit. 

Most  historical  implementations  use  kill  (-1,  sig)  from  a  super-user  process  to  | 
send  a  signal  to  all  processes  (excluding  system  processes  like  init).  This  use  of 
the  kill()  function  is  for  administrative  purposes  only;  portable  applications 
should  not  send  signals  to  processes  about  which  they  have  no  knowledge.  In 
addition,  there  are  semantic  variations  among  different  implementations  that, 
because  of  the  limited  use  of  this  feature,  were  not  necessary  to  resolve  by  stan¬ 
dardization.  System  V  implementations  also  use  kill  (-1,  sig)  from  a 
nonsuper-user  process  to  send  a  signal  to  all  processes  with  matching  user  IDs. 
This  use  was  considered  neither  sufficiently  widespread  nor  necessary  for  applica¬ 
tion  portability  to  warrant  inclusion  in  POSIX.1. 

There  was  initially  strong  sentiment  to  specify  that,  if  pid  specifies  that  a  signal  | 
be  sent  to  the  calling  process  and  that  signal  is  not  blocked,  that  signal  would  be 
delivered  before  kill()  returns.  This  would  permit  a  process  to  call  kill{ )  and  be 
guaranteed  that  the  call  never  return.  However,  historical  implementations  that 
provide  only  the  signalO  interface  make  only  the  weaker  guarantee  in  POSIX.1, 
because  they  only  deliver  one  signal  each  time  a  process  enters  the  kernel. 
Modifications  to  such  implementations  to  support  the  sigaction  ()  interface 
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generally  require  entry  to  the  kernel  following  return  from  a  signal-catching  func¬ 
tion,  in  order  to  restore  the  signal  mask.  Such  modifications  have  the  effect  of 
satisfying  the  stronger  requirement,  at  least  when  sigaction  ()  is  used,  but  not 
necessarily  when  signalO  is  used.  The  developers  of  POSIX.1  considered  making  | 
the  stronger  requirement  except  when  signalO  is  used,  but  felt  this  would  be  | 
unnecessarily  complex.  Implementors  are  encouraged  to  meet  the  stronger 
requirement  whenever  possible.  In  practice,  the  weaker  requirement  is  the  same, 
except  in  the  rare  case  when  two  signals  arrive  during  a  very  short  window.  This 
reasoning  also  applies  to  a  similar  requirement  for  sigprocmaskO . 

In  4.2BSD,  the  SIGCONT  signal  can  be  sent  to  any  descendant  process  regardless 
of  user-ID  security  checks.  This  allows  a  job-control  shell  to  continue  a  job  even  if 
processes  in  the  job  have  altered  their  user  IDs  (as  in  the  su  command).  In  keep¬ 
ing  with  the  addition  of  the  concept  of  sessions,  similar  functionality  is  provided 
by  allowing  the  SIGCONT  signal  to  be  sent  to  any  process  in  the  same  session, 
regardless  of  user-ID  security  checks.  This  is  less  restrictive  than  BSD  in  the 
sense  that  ancestor  processes  (in  the  same  session)  can  now  be  the  recipient.  It  is 
more  restrictive  than  BSD  in  the  sense  that  descendant  processes  that  form  new 
sessions  are  now  subject  to  the  user-ID  checks.  A  similar  relaxation  of  security  is 
not  necessary  for  the  other  job-control  signals  since  those  signals  are  typically 
sent  by  the  terminal  driver  in  recognition  of  special  characters  being  typed;  the 
terminal  driver  bypasses  all  security  checks. 

In  secure  implementations,  a  process  may  be  restricted  from  sending  a  signal  to  a 
process  having  a  different  security  label.  In  order  to  prevent  the  existence  or 
nonexistence  of  a  process  from  being  used  as  a  covert  channel,  such  processes 
should  appear  nonexistent  to  the  sender;  i.e.,  [ESRCH]  should  be  returned,  rather 
than  [EPERM],  if  pid  refers  only  to  such  processes. 

Existing  implementations  vary  on  the  result  of  a  killO  with  pid  indicating  an 
inactive  process  (a  terminated  process  that  has  not  been  waited  for  by  its  parent). 
Some  indicate  success  on  such  a  call  (subject  to  permission  checking),  while  others 
give  an  error  of  [ESRCH].  Since  POSIX.l’s  definition  of  process  lifetime  covers  inac¬ 
tive  processes,  the  [ESRCH]  error  as  described  is  inappropriate  in  this  case.  In 
particular,  this  means  that  an  application  cannot  have  a  parent  process  check  for 
termination  of  a  particular  child  with  killO  [usually  this  is  done  with  the  null  sig¬ 
nal;  this  can  be  done  reliably  with  waitpidO]- 

There  is  some  belief  that  the  name  killO  is  misleading,  since  the  function  is  not 
always  intended  to  cause  process  termination.  However,  the  name  is  common  to 
all  historical  implementations,  and  any  change  would  be  in  conflict  with  the  goal 
of  Minimal  Changes  to  Existing  Application  Code. 

B.3.3.3  Manipulate  Signal  Sets 

The  implementation  of  the  sigemptysetO  [or  sigfillsetO ]  functions  could  quite  trivi¬ 
ally  clear  (or  set)  all  the  bits  in  the  signal  set.  Alternatively,  it  would  be  reason¬ 
able  to  initialize  part  of  the  structure,  such  as  a  version  field,  to  permit  binary 
compatibility  between  releases  where  the  size  of  the  set  varies.  For  such  reasons, 
either  sigemptysetO  or  sigfillsetO  must  be  called  prior  to  any  other  use  of  the  sig¬ 
nal  set,  even  if  such  use  is  read-only  [e.g.,  as  an  argument  to  sigpending ()].  This 
function  is  not  intended  for  dynamic  allocation. 
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The  sigfillset ()  and  sigemptyset ()  functions  require  that  the  resulting  signal  set 
include  (or  exclude)  all  the  signals  defined  in  POSIX.l.  Although  it  is  outside  the 
scope  of  POSIX.1  to  place  this  requirement  on  signals  that  are  implemented  as 
extensions,  it  is  recommended  that  implementation-defined  signals  also  be 
affected  by  these  functions.  However,  there  may  be  a  good  reason  for  a  particular 
signal  not  to  be  affected.  For  example,  blocking  or  ignoring  an  implementation- 
defined  signal  may  have  undesirable  side  effects,  whereas  the  default  action  for 
that  signal  is  harmless.  In  such  a  case,  it  would  be  preferable  for  such  a  signal  to 
be  excluded  from  the  signal  set  returned  by  sigfillsetl ). 

In  earlier  drafts  of  POSIX.1  there  was  no  distinction  between  invalid  and  unsup¬ 
ported  signals  (the  names  of  optional  signals  that  were  not  supported  by  an 
implementation  were  not  defined  by  that  implementation).  The  [EINVAL]  error 
was  thus  specified  as  a  required  error  for  invalid  signals.  With  that  distinction,  it 
is  not  necessary  to  require  implementations  of  these  functions  to  determine 
whether  an  optional  signal  is  actually  supported,  as  that  could  have  a  significant 
performance  impact  for  little  value.  The  error  could  have  been  required  for 
invalid  signals  and  optional  for  unsupported  signals,  but  this  seemed  unneces¬ 
sarily  complex.  Thus,  the  error  is  optional  in  both  cases. 

B.3.3.4  Examine  and  Change  Signal  Action 

Although  POSIX.1  requires  that  signals  that  cannot  be  ignored  shall  not  be  added 
to  the  signal  mask  when  a  signal-catching  function  is  entered,  there  is  no  explicit 
requirement  that  subsequent  calls  to  sigaction  ()  reflect  this  in  the  information 
returned  in  the  oact  argument.  In  other  words,  if  SIGKILL  is  included  in  the 
sajnask  field  of  act,  it  is  unspecified  whether  or  not  a  subsequent  call  to  sigac¬ 
tionO  will  return  with  SIGKILL  included  in  the  sajnask  field  of  oact. 

The  SA_NOCLDSTOP  flag,  when  supplied  in  the  act->sa  Jlags  parameter,  allows 
overloading  SIGCHLD  with  the  System  V  semantics  that  each  SIGCLD  signal  indi¬ 
cates  a  single  terminated  child.  Most  portable  applications  that  catch  SIGCHLD 
are  expected  to  install  signal-catching  functions  that  repeatedly  call  the  waitpid () 
function  with  the  WNOHANG  flag  set,  acting  on  each  child  for  which  status  is 
returned,  until  waitpidO  returns  zero.  If  stopped  children  are  not  of  interest,  the 
use  of  the  SA_NOCLDSTOP  flag  can  prevent  the  overhead  from  invoking  the 
signal-catching  routine  when  they  stop. 

Some  historical  implementations  also  define  other  mechanisms  for  stopping  | 
processes,  such  as  the  ptrace ()  function.  These  implementations  usually  do  not 
generate  a  SIGCHLD  signal  when  processes  stop  due  to  this  mechanism;  however, 
that  is  beyond  the  scope  of  POSIX.1. 

POSIX.1  requires  that  calls  to  sigactionO  that  supply  a  NULL  act  argument 
succeed,  even  in  the  case  of  signals  that  cannot  be  caught  or  ignored  (i.e.,  SIGKILL 
or  SIGSTOP).  The  System  V  signalO  and  BSD  sigvecO  functions  return  [EINVAL] 
in  these  cases  and,  in  this  respect,  their  behavior  varies  from  sigaction  (). 

POSIX.1  requires  that  sigactionO  properly  save  and  restore  a  signal  action  set  up 
by  the  C  Standard  {2}  signalO  function.  However,  there  is  no  guarantee  that  the 
reverse  is  true,  nor  could  there  be  given  the  greater  amount  of  information  con¬ 
veyed  by  the  sigaction  structure.  Because  of  this,  applications  should  avoid  using 
both  functions  for  the  same  signal  in  the  same  process.  Since  this  cannot  always 
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2552  be  avoided  in  case  of  general-purpose  library  routines,  they  should  always  be 

2553  implemented  with  sigactioni). 

2554  It  was  intended  that  the  signal ()  function  should  be  implementable  as  a  library  | 

2555  routine  using sigactioni). 

2556  B.3.3.5  Examine  and  Change  Blocked  Signals 

2557  When  a  process’s  signal  mask  is  changed  in  a  signal-catching  function  that  is 

2558  installed  by  sigactioni),  the  restoration  of  the  signal  mask  on  return  from  the 

2559  signal-catching  function  overrides  that  change  [see  sigactioni )].  If  the  signal- 

2560  catching  function  was  installed  with  signali ),  it  is  unspecified  whether  this 

2561  occurs. 

2562  See  B.3.3.2  for  a  discussion  of  the  requirement  on  delivery  of  signals. 

2563  B.3.3.6  Examine  Pending  Signals 

2564  There  is  no  additional  rationale  provided  for  this  subclause. 

2565  B.3.3.7  Wait  for  a  Signal 

2566  Normally,  at  the  beginning  of  a  critical  code  section,  a  specified  set  of  signals  is 

2567  blocked  using  the  sigprocmaski )  function.  When  the  process  has  completed  the 

2568  critical  section  and  needs  to  wait  for  the  previously  blocked  signal(s),  it  pauses  by 

2569  calling  sigsuspendi )  with  the  mask  that  was  returned  by  the  sigprocmaski)  call. 

2570  B.3.4  Timer  Operations 

2571  B.3.4.1  Schedule  Alarm 

2572  Many  historical  implementations  (including  Version  7  and  System  V)  allow  an 

2573  alarm  to  occur  up  to  a  second  early.  Other  implementations  allow  alarms  up  to 

2574  half  a  second  or  one  clock  tick  early  or  do  not  allow  them  to  occur  early  at  all.  The  | 

2575  latter  is  considered  most  appropriate,  since  it  gives  the  most  predictable  behavior, 

2576  especially  since  the  signal  can  always  be  delayed  for  an  indefinite  amount  of  time 

2577  due  to  scheduling.  Applications  can  thus  choose  the  seconds  argument  as  the 

2578  minimum  amount  of  time  they  wish  to  have  elapse  before  the  signal. 

2579  The  term  “real  time”  here  and  elsewhere  [sleep (),  timesi )]  is  intended  to  mean 

2580  “wall  clock”  time  as  common  English  usage,  and  has  nothing  to  do  with  “realtime 

2581  operating  systems.”  It  is  in  contrast  to  “virtual  time,”  which  could  be  misinter- 

2582  preted  if  just  “time”  were  used. 

2583  In  some  implementations,  including  4.3BSD,  very  large  values  of  the  seconds 

2584  argument  are  silently  rounded  down  to  an  implementation-defined  maximum 

2585  value.  This  maximum  is  large  enough  (on  the  order  of  several  months)  that  the 

2586  effect  is  not  noticeable. 

2587  Application  writers  should  note  that  the  type  of  the  argument  seconds  and  the 

2588  return  value  of  alarmi)  is  unsigned  int.  That  means  that  a  Strictly  Conforming 

2589  POSIX.1  Application  cannot  pass  a  value  greater  than  the  minimum  guaranteed 
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value  for  {UINT_MAX},  which  the  C  Standard  {2}  sets  as  65535,  and  any  applica¬ 
tion  passing  a  larger  value  is  restricting  its  portability.  A  different  type  was  con-  | 
sidered,  but  historical  implementations,  including  those  with  a  16-bit  int  type,  | 
consistently  use  either  unsigned  int  or  int. 

Application  writers  should  be  aware  of  possible  interactions  when  the  same  pro¬ 
cess  uses  both  the  alarm( )  and  sleep ()  functions  [see  sleepO  and  B.3.4.3]. 

B.3.4.2  Suspend  Process  Execution 

Many  common  uses  ofpauseO  have  timing  windows.  The  scenario  involves  check¬ 
ing  a  condition  related  to  a  signal  and,  if  the  signal  has  not  occurred,  calling 
pause  ().  When  the  signal  occurs  between  the  check  and  the  call  to  pause  (),  the 
process  often  blocks  indefinitely.  The  sigprocmask ()  and  sigsuspendi)  functions 
can  be  used  to  avoid  this  type  of  problem. 

B.3.4.3  Delay  Process  Execution 

There  are  two  general  approaches  to  the  implementation  of  the  sleep  ()  function. 
One  is  to  use  the  alarm{)  function  to  schedule  a  SIGALRM  signal  and  then 
suspend  the  process  waiting  for  that  signal.  The  other  is  to  implement  an 
independent  facility.  POSIX.1  permits  either  approach. 

In  order  to  comply  with  the  wording  of  the  introduction  to  Section  3,  that  no  prim-  | 
itive  shall  change  a  process  attribute  unless  explicitly  described  by  POSIX.1,  an 
implementation  using  SIGALRM  must  carefully  take  into  account  any  SIGALRM 
signal  scheduled  by  previous  alarm  ()  calls,  the  action  previously  established  for 
SIGALRM,  and  whether  SIGALRM  was  blocked.  If  a  SIGALRM  has  been  scheduled 
before  the  sleep  ()  would  ordinarily  complete,  the  sleep ()  must  be  shortened  to  that 
time  and  a  SIGALRM  generated  (possibly  simulated  by  direct  invocation  of  the 
signal-catching  function)  before  sleep ()  returns.  If  a  SIGALRM  has  been  scheduled 
after  the  sleep ()  would  ordinarily  complete,  it  must  be  rescheduled  for  the  same 
time  before  sleep ()  returns.  The  action  and  blocking  for  SIGALRM  must  be  saved 
and  restored. 

Historical  implementations  often  implement  the  SIGALRM-based  version  using 
alarm()  and  pause ().  One  such  implementation  is  prone  to  infinite  hangups,  as 
described  in  B.3.4.2.  Another  such  implementation  uses  the  C  language  setjmpO 
and  longjmp  ()  functions  to  avoid  that  window.  That  implementation  introduces  a 
different  problem:  when  the  SIGALRM  signal  interrupts  a  signal-catching  function 
installed  by  the  user  to  catch  a  different  signal,  the  longjmp  ()  aborts  that  signal- 
catching  function.  An  implementation  based  on  sigprocmask  (),  alarm  (),  and  sig- 
suspendi)  can  avoid  these  problems. 

Despite  all  reasonable  care,  there  are  several  very  subtle,  but  detectable  and  una¬ 
voidable,  differences  between  the  two  types  of  implementations.  These  are  the 
cases  mentioned  in  POSIX.1  where  some  other  activity  relating  to  SIGALRM  takes 
place,  and  the  results  are  stated  to  be  unspecified.  All  of  these  cases  are 
sufficiently  unusual  as  not  to  be  of  concern  to  most  applications. 

(See  also  the  discussion  of  the  term  “real  time”  in  B. 3.4.1.) 
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2632  Because  sleep  ()  can  be  implemented  using  alarm  (),  the  discussion  about  alarms 

2633  occurring  early  under  B. 3.4.1  applies  to  sleep ()  as  well. 

2634  Application  writers  should  note  that  the  type  of  the  argument  seconds  and  the 

2635  return  value  of  sleep  ()  is  unsigned  int.  That  means  that  a  Strictly  Conforming 

2636  POSIX.  1  Application  cannot  pass  a  value  greater  than  the  minimum  guaranteed 

2637  value  for  {UINT_MAX},  which  the  C  Standard  {2}  sets  as  65  535,  and  any  applica- 

2638  tion  passing  a  larger  value  is  restricting  its  portability.  A  different  type  was  con-  | 

2639  sidered,  but  historical  implementations,  including  those  with  a  16-bit  int  type,  | 

2640  consistently  use  either  unsigned  int  or  int. 

2641  Scheduling  delays  may  cause  the  process  to  return  from  the  sleep  ()  function 

2642  significantly  after  the  requested  time.  In  such  cases,  the  return  value  should  be 

2643  set  to  zero,  since  the  formula  (requested  time  minus  the  time  actually  spent) 

2644  yields  a  negative  number  and  sleep ()  returns  an  unsigned  int. 


2645  B.4  Process  Environment 

2646  B.4.1  Process  Identification 

2647  B.4.1. 1  Get  Process  and  Parent  Process  IDs 

2648  There  is  no  additional  rationale  provided  for  this  subclause. 

2649  B.4.2  User  Identification 

2650  B.4.2.1  Get  Real  User,  Effective  User,  Real  Group,  and  Effective  Group 

2651  IDS 

2652  There  is  no  additional  rationale  provided  for  this  subclause. 

2653  B.4.2.2  Set  User  and  Group  IDs 

2654  The  saved  set-user-ID  capability  allows  a  program  to  regain  the  effective  user  ID 

2655  established  at  the  last  exec  call.  Similarly,  the  saved  set-group-ID  capability 

2656  allows  a  program  to  regain  the  effective  group  ID  established  at  the  last  exec  call. 

2657  These  two  capabilities  are  derived  from  System  V.  Without  them,  a  program  may 

2658  have  to  run  as  super-user  in  order  to  perform  the  same  functions,  because  super- 

2659  user  can  write  on  the  user’s  files.  This  is  a  problem  because  such  a  program  can 

2660  write  on  any  user’s  files,  and  so  must  be  carefully  written  to  emulate  the  permis- 

2661  sions  of  the  calling  process  properly. 

2662  A  process  with  appropriate  privilege  on  a  system  with  this  saved  ID  capability 

2663  establishes  all  relevant  IDs  to  the  new  value,  since  this  function  is  used  to  estab- 

2664  lish  the  identity  of  the  user  during  login  or  su.  Any  change  to  this  behavior 

2665  would  be  dangerous  since  it  involves  programs  that  need  to  be  trusted. 
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2666  The  behavior  of  4.2BSD  and  4.3BSD  that  allows  setting  the  real  ID  to  the  effective 

2667  ID  is  viewed  as  a  value-dependent  special  case  of  appropriate  privilege. 

2668  B.4.2.3  Get  Supplementary  Group  IDs 

2669  The  related  function  setgroups  ()  is  a  privileged  operation  and  therefore  is  not 

2670  covered  by  POSIX.1. 

2671  As  implied  by  the  definition  of  supplementary  groups,  the  effective  group  ID  may  | 

2672  appear  in  the  array  returned  by  getgroups ()  or  it  may  be  returned  only  by 

2673  getegidi).  Duplication  may  exist,  but  the  application  needs  to  call  getegidi )  to  be 

2674  sure  of  getting  all  of  the  information.  Various  implementation  variations  and  | 

2675  administrative  sequences  will  cause  the  set  of  groups  appearing  in  the  result  of  | 

2676  getgroups ()  to  vary  in  order  and  as  to  whether  the  effective  group  ID  is  included,  | 

2677  even  when  the  set  of  groups  is  the  same  (in  the  mathematical  sense  of  “set”).  (The  | 

2678  history  of  a  process  and  its  parents  could  affect  the  details  of  result.) 

2679  Applications  writers  should  note  that  {NGROUPS_MAX}  is  not  necessarily  a  con-  | 

2680  stant  on  all  implementations.  I 

2681  B.4.2.4  Get  User  Name 

2682  The  getlogini)  function  returns  a  pointer  to  the  user’s  login  name.  The  same  user 

2683  ID  may  be  shared  by  several  login  names.  If  it  is  desired  to  get  the  user  database 

2684  entry  that  is  used  during  login,  the  result  of  getloginO  should  be  used  to  provide 

2685  the  argument  to  the  getpwnami)  function.  (This  might  be  used  to  determine  the 

2686  user’s  login  shell,  particularly  where  a  single  user  has  multiple  login  shells  with 

2687  distinct  login  names,  but  the  same  user  ID.) 

2688  The  information  provided  by  the  cuseridi )  function,  which  was  originally  defined 

2689  in  IEEE  Std  1003.1-1990  and  subsequently  removed,  can  be  obtained  by  the 

2690  following: 

2691  getpwuid  (geteuid  ( )  ) 

2692  while  the  information  provided  by  historical  implementations  of  cuseridi)  can  be 

2693  obtained  by: 

2694  getpwuid  (getuid  ()  )  I 

2695  B.4.3  Process  Groups 

2696  B.4.3. 1  Get  Process  Group  ID 

2697  4.3BSD  provides  a  getpgrp  ()  function  that  returns  the  process  group  ID  for  a 

2698  specified  process.  Although  this  function  is  used  to  support  job  control,  all  known 

2699  job-control  shells  always  specify  the  calling  process  with  this  function.  Thus,  the 

2700  simpler  System  V  getpgrpi)  suffices,  and  the  added  complexity  of  the  4.3BSD 

2701  getpgrpi)  has  been  omitted  from  POSIX.1. 
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B.4.3.2  Create  Session  and  Set  Process  Group  ED 

The  setsidO  function  is  similar  to  the  setpgrp  ()  function  of  System  V.  System  V, 
without  job  control,  groups  processes  into  process  groups  and  creates  new  process 
groups  via  setpgrp  ();  only  one  process  group  may  be  part  of  a  login  session. 

Job  control  allows  multiple  process  groups  within  a  login  session.  In  order  to 
limit  job-control  actions  so  that  they  can  only  affect  processes  in  the  same  login 
session,  POSIX.l  adds  the  concept  of  a  session  that  is  created  via  setsidO.  The  set¬ 
sidO  function  also  creates  the  initial  process  group  contained  in  the  session. 
Additional  process  groups  can  be  created  via  the  setpgidO  function.  A  System  V 
process  group  would  correspond  to  a  POSIX.  1  session  containing  a  single  POSIX.1 
process  group.  Note  that  this  function  requires  that  the  calling  process  not  be  a 
process  group  leader.  The  usual  way  to  ensure  this  is  true  is  to  create  a  new  pro¬ 
cess  with  fork 0  and  have  it  call  setsidO .  The  fork 0  function  guarantees  that  the 
process  ID  of  the  new  process  does  not  match  any  existing  process  group  ID. 

B.4.3.3  Set  Process  Group  ED  for  Job  Control 

The  setpgid( )  function  is  used  to  group  processes  together  for  the  purpose  of  sig¬ 
naling,  placement  in  foreground  or  background,  and  other  job-control  actions.  See 
B.2.2.2. 

The  setpgidO  function  is  similar  to  the  setpgrpO  function  of  4.2BSD,  except  that 
4.2BSD  allowed  the  specified  new  process  group  to  assume  any  value.  This 
presents  certain  security  problems  and  is  more  flexible  than  necessary  to  support 
job  control. 

To  provide  tighter  security,  setpgidO  only  allows  the  calling  process  to  join  a  pro¬ 
cess  group  already  in  use  inside  its  session  or  create  a  new  process  group  whose 
process  group  ID  was  equal  to  its  process  ID. 

When  a  job-control  shell  spawns  a  new  job,  the  processes  in  the  job  must  be 
placed  into  a  new  process  group  via  setpgidO .  There  are  two  timing  constraints 
involved  in  this  action: 

(1)  The  new  process  must  be  placed  in  the  new  process  group  before  the 
appropriate  program  is  launched  via  one  of  the  exec  functions. 

(2)  The  new  process  must  be  placed  in  the  new  process  group  before  the  shell 
can  correctly  send  signals  to  the  new  process  group. 

To  address  these  constraints,  the  following  actions  are  performed:  The  new 
processes  call  setpgidO  to  alter  their  own  process  groups  after  forkO  but  before 
exec.  This  satisfies  the  first  constraint.  Under  4.3BSD,  the  second  constraint  is 
satisfied  by  the  synchronization  property  of  vfork ();  that  is,  the  shell  is  suspended 
until  the  child  has  completed  the  exec ,  thus  ensuring  that  the  child  has  completed 
the  setpgidO-  A  new  version  of  forkO  with  this  same  synchronization  property  | 
was  considered,  but  it  was  decided  instead  to  merely  allow  the  parent  shell  pro-  | 
cess  to  adjust  the  process  group  of  its  child  processes  via  setpgidO •  Both  timing 
constraints  are  now  satisfied  by  having  both  the  parent  shell  and  the  child 
attempt  to  adjust  the  process  group  of  the  child  process;  it  does  not  matter  which 
succeeds  first. 
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2745  Because  it  would  be  confusing  to  an  application  to  have  its  process  group  change 

2746  after  it  began  executing  (i.e.,  after  exec )  and  because  the  child  process  would 

2747  already  have  adjusted  its  process  group  before  this,  the  [EACCES]  error  was  added 

2748  to  disallow  this. 

2749  One  nonobvious  use  of  setpgidi)  is  to  allow  a  job-control  shell  to  return  itself  to  its 

2750  original  process  group  (the  one  in  effect  when  the  job-control  shell  was  executed). 

2751  A  job-control  shell  does  this  before  returning  control  back  to  its  parent  when  it  is 

2752  terminating  or  suspending  itself  as  a  way  of  restoring  its  job  control  “state”  back 

2753  to  what  its  parent  would  expect.  (Note  that  the  original  process  group  of  the  job- 

2754  control  shell  typically  matches  the  process  group  of  its  parent,  but  this  is  not 

2755  necessarily  always  the  case.)  See  also  B.7.2.4. 

2756  B.4.4  System  Identification 

2757  B.4.4. 1  System  Name 

2758  The  values  of  the  structure  members  are  not  constrained  to  have  any  relation  to 

2759  the  version  of  POSIX.l  implemented  in  the  operating  system.  An  application 

2760  should  instead  depend  on  {_POSIX_VERSION}  and  related  constants  defined  in  2.9. 

2761  POSIX.1  does  not  define  the  sizes  of  the  members  of  the  structure  and  permits 

2762  them  to  be  of  different  sizes,  although  most  implementations  define  them  all  to  be 

2763  the  same  size:  eight  bytes  plus  one  byte  for  the  string  terminator.  That  size  for 

2764  nodename  is  not  enough  for  use  with  many  networks. 

2765  The  uname  ()  function  is  specific  to  System  III,  System  V,  and  related  implementa- 

2766  tions,  and  it  does  not  exist  in  Version  7  or  4.3BSD.  The  values  it  returns  are  set 

2767  at  system  compile  time  in  those  historical  implementations.  I 

2768  4.3BSD  has  gethostnameO  and  gethostidi),  which  return  a  symbolic  name  and  a 

2769  numeric  value,  respectively.  There  are  related  sethostnameO  and  sethostidO 

2770  functions  that  are  used  to  set  the  values  the  other  two  functions  return.  The 

2771  length  of  the  host  name  is  limited  to  31  characters  in  most  implementations  and 

2772  the  host  ID  is  a  32-bit  integer. 

2773  B.4.5  Time 

2774  The  time ()  function  returns  a  value  in  seconds  (type  timejt )  while  times  ()  returns 

2775  a  set  of  values  in  clock  ticks  (type  clock  J).  Some  historical  implementations,  such  | 

2776  as  4.3BSD,  have  mechanisms  capable  of  returning  more  precise  times  [see  the 

2777  description  of  gettimeof day ()  in  B.4.5. 1].  A  generalized  timing  scheme  to  unify 

2778  these  various  timing  mechanisms  has  been  proposed  but  not  adopted  in  POSIX.1.  | 

2779  B.4.5.1  Get  System  Time 

2780  Implementations  in  which  timejt  is  a  32-bit  signed  integer  (most  historical  imple- 

2781  mentations)  will  fail  in  the  year  2038.  This  version  of  POSIX.1  does  not  address 

2782  this  problem.  However,  the  use  of  the  new  timej  type  is  mandated  in  order  to 

2783  ease  the  eventual  fix. 
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2784  The  use  of  the  header  <t  ime .  h>,  instead  of  <sys /types  .  h>,  allows  compatibil- 

2785  ity  with  the  C  Standard  {2}. 

2786  Many  historical  implementations  (including  Version  7)  and  the  1984  /usr /group 

2787  Standard  {B59}  use  long  instead  of  timej.  POSIX.l  uses  the  latter  type  in  order 

2788  to  agree  with  the  C  Standard  {2}. 

2789  4.3BSD  includes  time{)  only  as  an  interface  to  the  more  flexible  gettimeofday () 

2790  function. 

2791  B.4.5.2  Get  Process  Times 

2792  The  accuracy  of  the  times  reported  is  intentionally  left  unspecified  to  allow  imple- 

2793  mentations  flexibility  in  design,  from  uniprocessor  to  multiprocessor  networks. 

2794  The  inclusion  of  times  of  child  processes  is  recursive,  so  that  a  parent  process  may 

2795  collect  the  total  times  of  all  of  its  descendants.  But  the  times  of  a  child  are  only 

2796  added  to  those  of  its  parent  when  its  parent  successfully  waits  on  the  child.  Thus, 

2797  it  is  not  guaranteed  that  a  parent  process  will  always  be  able  to  see  the  total 

2798  times  of  all  its  descendants. 

2799  (See  also  the  discussion  of  the  term  “real  time”  in  B.3.4.1.) 

2800  If  the  type  clock  Jt  is  defined  to  be  a  signed  32-bit  integer,  it  will  overflow  in  some- 

2801  what  more  than  a  year  if  there  are  60  clock  ticks  per  second,  or  less  than  a  year  if  | 

2802  there  are  100.  There  are  individual  systems  that  run  continuously  for  longer  than 

2803  that.  POSIX.l  permits  an  implementation  to  make  the  reference  point  for  the 

2804  returned  value  be  the  startup  time  of  the  process,  rather  than  system  startup 

2805  time. 

2806  The  term  “charge”  in  this  context  has  nothing  to  do  with  billing  for  services.  The 

2807  operating  system  accounts  for  time  used  in  this  way.  That  information  must  be 

2808  correct,  regardless  of  how  that  information  is  used. 

2809  B.4.6  Environment  Variables 

2810  B.4.6. 1  Environment  Access 

2811  Additional  functions  putenv ()  and  clearenvO  were  considered  but  rejected  because 

2812  they  were  considered  to  be  more  oriented  towards  system  administration  than 

2813  ordinary  application  programs.  This  is  being  reconsidered  for  an  amendment  to  | 

2814  POSIX.1  because  uses  from  within  an  application  have  been  identified  since  the  | 

2815  decision  was  made. 

2816  It  was  proposed  that  this  function  is  properly  part  of  Section  8.  It  is  an  extension  | 

2817  to  a  function  in  the  C  Standard  {2}.  Because  this  function  should  be  available  | 

2818  from  any  language,  not  just  C,  it  appears  here,  to  separate  it  from  the  material  in  | 

2819  Section  8,  which  is  specific  to  the  C  binding.  (The  localization  extensions  to  C  are 

2820  not,  at  this  time,  appropriate  for  other  languages.) 
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2821  B.4.7  Terminal  Identification 

2822  The  difference  between  ctermidO  and  ttynameO  is  that  ttynameO  must  be  passed 

2823  a  file  descriptor  and  returns  the  pathname  of  the  terminal  associated  with  that 

2824  file  descriptor,  while  ctermid{ )  returns  a  string  (such  as  /dev/tty)  that  will  refer 

2825  to  the  controlling  terminal  if  used  as  a  pathname.  Thus  ttynameO  is  useful  only  if 

2826  the  process  already  has  at  least  one  file  open  to  a  terminal. 

2827  The  historical  value  of  ctermidO  is  /dev/ tty;  this  is  acceptable.  The  ctermidO 

2828  function  should  not  be  used  to  determine  if  a  process  actually  has  a  controlling 

2829  terminal,  but  merely  the  name  that  would  be  used. 

2830  B.4.7. 1  Generate  Terminal  Pathname 

2831  L_ctermid  must  be  defined  appropriately  for  a  given  implementation  and  must  be 

2832  greater  than  zero  so  that  array  declarations  using  it  are  accepted  by  the  compiler. 

2833  The  value  includes  the  terminating  null  byte. 

2834  B.4.7.2  Determine  Terminal  Device  Name 

2835  The  term  “terminal”  is  used  instead  of  the  historical  term  “terminal  device”  in 

2836  order  to  avoid  a  reference  to  an  undefined  term. 


2837  B.4.8  Configurable  System  Variables 


2838  This  subclause  was  added  in  response  to  requirements  of  application  developers  | 

2839  and  of  system  vendors  who  deal  with  many  international  system  configurations.  | 

2840  It  is  closely  related  to  B.5.7  as  well. 

2841  Although  a  portable  application  can  run  on  all  systems  by  never  demanding  more 

2842  resources  than  the  minimum  values  published  in  POSIX.l,  it  is  useful  for  that 

2843  application  to  be  able  to  use  the  actual  value  for  the  quantity  of  a  resource  avail- 

2844  able  on  any  given  system.  To  do  this,  the  application  will  make  use  of  the  value  of 

2845  a  symbolic  constant  in  <limits  .  h>  or  <unistd.  h>. 

2846  However,  once  compiled,  the  application  must  still  be  able  to  cope  if  the  amount  of 

2847  resource  available  is  increased.  To  that  end,  an  application  may  need  a  means  of 

2848  determining  the  quantity  of  a  resource,  or  the  presence  of  an  option,  at  execution 

2849  time. 


2850  Two  examples  are  offered: 


2851 

2852 

2853 

2854 

2855 


(1)  Applications  may  wish  to  act  differently  on  systems  with  or  without  job 
control.  Applications  vendors  who  wish  to  distribute  only  a  single  binary 
package  to  all  instances  of  a  computer  architecture  would  be  forced  to 
assume  job  control  is  never  available  if  it  were  to  rely  solely  on  the 
<unistd.h>  value  published  in  POSIX.1. 


2856 

2857 

2858 

2859 

2860 


(2)  International  applications  vendors  occasionally  require  knowledge  of  the  | 
number  of  clock  ticks  per  second.  Without  the  facilities  of  this  subclause,  | 
they  would  be  required  to  either  distribute  their  applications  partially  in  | 
source  form  or  to  have  50  Hz  and  60  Hz  versions  for  the  various  countries  | 
in  which  they  operate. 
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2861  It  is  the  knowledge  that  many  applications  are  actually  distributed  widely  in  exe- 

2862  cutable  form  that  lead  to  this  facility.  If  limited  to  the  most  restrictive  values  in 

2863  the  headers,  such  applications  would  have  to  be  prepared  to  accept  the  most  lim- 

2864  ited  environments  offered  by  the  smallest  microcomputers.  Although  this  is 

2865  entirely  portable,  there  was  a  consensus  that  they  should  be  able  to  take  advan-  | 

2866  tage  of  the  facilities  offered  by  large  systems,  without  the  restrictions  associated 

2867  with  source  and  object  distributions. 

2868  During  the  discussions  of  this  feature,  it  was  pointed  out  that  it  is  almost  always 

2869  possible  for  an  application  to  discern  what  a  value  might  be  at  run-time  by  suit- 

2870  ably  testing  the  various  interfaces  themselves.  And,  in  any  event,  it  could  always 

2871  be  written  to  adequately  deal  with  error  returns  from  the  various  functions.  In 

2872  the  end,  it  was  felt  that  this  imposed  an  unreasonable  level  of  complication  and 

2873  sophistication  on  the  application  writer. 

2874  This  run-time  facility  is  not  meant  to  provide  ever-changing  values  that  applica- 

2875  tions  will  have  to  check  multiple  times.  The  values  are  seen  as  changing  no  more 

2876  frequently  than  once  per  system  initialization,  such  as  by  a  system  administrator 

2877  or  operator  with  an  automatic  configuration  program.  POSIX.  1  specifies  that  they 

2878  shall  not  change  within  the  lifetime  of  the  process. 

2879  Some  values  apply  to  the  system  overall  and  others  vary  at  the  file  system  or 

2880  directory  level.  These  latter  are  described  in  B.5.7. 

2881  B.4.8.1  Get  Configurable  System  Variables 

2882  Note  that  all  values  returned  must  be  expressible  as  integers.  String  values  were  | 

2883  considered,  but  the  additional  flexibility  of  this  approach  was  rejected  due  to  its 

2884  added  complexity  of  implementation  and  use. 

2885  Some  values,  such  as  {PATH_MAX},  are  sometimes  so  large  that  they  must  not  be 

2886  used  to,  say,  allocate  arrays.  The  sysconfX )  function  will  return  a  negative  value 

2887  to  show  that  this  symbolic  constant  is  not  even  defined  in  this  case. 

2888  B.4.8.1. 1  Special  Symbol  {CLK_TCK}  | 

2889  {CLK_TCK}  appears  in  POSIX.  1  for  backwards  compatibility  with  IEEE  Std  | 

2890  1003.1-1988.  Its  use  is  obsolescent.  | 

2891  B.4.8.2  Get  Password  From  User  | 

2892  The  getpass  ()  function  was  explicitly  excluded  from  POSIX.  1  because  it  was  found  | 

2893  that  the  name  was  misleading,  and  it  provided  no  functionality  that  the  user  | 

2894  could  not  easily  implement  within  POSIX.  1.  The  implication  of  some  form  of  secu-  | 

2895  rity,  which  was  not  actually  provided,  exceeded  the  small  gain  in  convenience. 
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B.5  Files  and  Directories 

See  pathname  resolution . 

The  wording  regarding  the  group  of  a  newly  created  regular  file,  directory,  or 
FIFO  in  open(),  mkdir(),  mkfifoO,  respectively,  defines  the  two  acceptable 
behaviors  in  order  to  permit  both  the  System  V  (and  Version  7)  behavior  (in  which 
the  group  of  the  new  object  is  set  to  the  effective  group  ID  of  the  creating  process) 
and  the  4.3BSD  behavior  (in  which  the  new  object  has  the  group  of  its  parent 
directory).  An  application  that  needs  a  file  to  be  created  specifically  in  one  or  the 
other  of  the  possible  groups  should  use  chown()  to  ensure  the  new  group  regard¬ 
less  of  the  style  of  groups  the  interface  implements.  Most  applications  will  not 
and  should  not  be  concerned  with  the  group  ID  of  the  file. 


B.5.1  Directories 

Historical  implementations  prior  to  4.2BSD  had  no  special  functions,  types,  or 
headers  for  directory  access.  Instead,  directories  were  read  with  read()  and  each 
program  that  did  so  had  code  to  understand  the  internal  format  of  directory  files. 
Many  such  programs  did  not  correctly  handle  the  case  of  a  maximum-length  (his¬ 
torically  fourteen  character)  filename  and  would  neglect  to  add  a  null  character 
string  terminator  when  doing  comparisons.  The  access  methods  in  POSIX.1  elim¬ 
inate  that  bug,  as  well  as  hiding  differences  in  implementations  of  directories  or 
file  systems. 

The  directory  access  functions  originally  selected  for  POSIX.1  were  derived  from  | 
4.2BSD,  were  adopted  in  System  V  Release  3,  and  are  in  SVID  {B39}  Volume  3, 
with  the  exception  of  a  type  difference  for  the  d_ino  field.  That  field  represents 
implementation-dependent  or  even  file  system-dependent  information  (the  i-node 
number  in  most  implementations).  Since  the  directory  access  mechanism  is 
intended  to  be  implementation-independent,  and  since  only  system  programs,  not 
ordinary  applications,  need  to  know  about  the  i-node  number  (or  file  serial 
number)  in  this  context,  the  d_ino  field  does  not  appear  in  POSIX.1.  Also,  pro¬ 
grams  that  want  this  information  can  get  it  with  stat( ). 

B.5.1. 1  Format  of  Directory  Entries 

Information  similar  to  that  in  the  header  <dirent.h>  is  contained  in  a  file 
<sys/dir.h>  in  4.2BSD  and  4.3BSD.  The  equivalent  in  these  implementations 
of  struct  dirent  from  POSIX.1  is  struct  direct.  The  filename  was  changed  because 
the  name  <sys/dir.h>  was  also  used  in  earlier  implementations  to  refer  to 
definitions  related  to  the  older  access  method;  this  produced  name  conflicts.  The 
name  of  the  structure  was  changed  because  POSIX.1  does  not  completely  define 
what  is  in  the  structure,  so  it  could  be  different  on  some  implementations  from 
struct  direct. 

The  name  of  an  array  of  char  of  an  unspecified  size  should  not  be  used  as  an  | 
lvalue.  Use  of  I 

sizeof  (d_name) 

is  incorrect;  use 
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2938  strlen  (d_name) 

2939  instead. 

2940  The  array  of  char  djiame  is  not  a  fixed  size.  Implementations  may  need  to  | 

2941  declare  struct  dirent  with  an  array  size  for  djiame  of  1,  but  the  actual  number  of 

2942  characters  provided  matches  (or  only  slightly  exceeds)  the  length  of  the  file  name. 

2943  Currently,  implementations  are  excluded  if  they  have  djiame  with  type  char  * . 

2944  Lacking  experience  of  such  implementations,  the  developers  of  POSIX.1  declined  | 

2945  to  try  to  describe  in  standards  language  what  to  do  if  either  type  were  permitted. 

2946  B.5.1.2  Directory  Operations 

2947  Based  on  historical  implementations,  the  rules  about  file  descriptors  apply  to 

2948  directory  streams  as  well.  However,  POSIX.1  does  not  mandate  that  the  directory 

2949  stream  be  implemented  using  file  descriptors.  The  description  of  opendir() 

2950  clarifies  that  if  a  file  descriptor  is  used  for  the  directory  stream  it  is  mandatory 

2951  that  closedir()  deallocate  the  file  descriptor.  When  a  file  descriptor  is  used  to  | 

2952  implement  the  directory  stream,  it  behaves  as  if  the  FD_CLOEXEC  had  been  set  | 

2953  for  the  file  descriptor.  | 

2954  The  returned  value  of  readdir{)  merely  represents  a  directory  entry.  No 

2955  equivalence  should  be  inferred. 

2956  The  directory  entries  for  dot  and  dot-dot  are  optional.  POSIX.1  does  not  provide  a  | 

2957  way  to  test  a  priori  for  their  existence  because  an  application  that  is  portable  | 

2958  must  be  written  to  look  for  (and  usually  ignore)  those  entries.  Writing  code  that  | 

2959  presumes  that  they  are  the  first  two  entries  does  not  always  work,  as  many  imple-  | 

2960  mentations  permit  them  to  be  other  than  the  first  two  entries,  with  a  “normal”  | 

2961  entry  preceding  them.  There  is  negligible  value  in  providing  a  way  to  determine  | 

2962  what  the  implementation  does  because  the  code  to  deal  with  dot  and  dot-dot  must  | 

2963  be  written  in  any  case  and  because  such  a  flag  would  add  to  the  list  of  those  flags  | 

2964  (which  has  proven  in  itself  to  be  objectionable)  and  might  be  abused.  | 

2965  Since  the  structure  and  buffer  allocation,  if  any,  for  directory  operations  are 

2966  defined  by  the  implementation,  POSIX.1  imposes  no  portability  requirements  for 

2967  erroneous  program  constructs,  erroneous  data,  or  the  use  of  indeterminate  values 

2968  such  as  the  use  or  referencing  of  a  dirp  value  or  a  dirent  structure  value  after  a 

2969  directory  stream  has  been  closed  or  after  a  fork{)  or  one  of  the  exec  function  calls. 

2970  Historical  implementations  of  readdir( )  obtain  multiple  directory  entries  on  a  sin- 

2971  gle  read  operation,  which  permits  subsequent  readdir()  operations  to  operate 

2972  from  the  buffered  information.  Any  wording  that  required  each  successful  read- 
2913  dir{)  operation  to  mark  the  directory  stjatime  field  for  update  would  militate 

2974  against  the  historical  performance-oriented  implementations. 

2975  Since  readdir{ )  returns  NULL  both: 

2976  (1)  When  it  detects  an  error,  and 

2977  (2)  When  the  end  of  the  directory  is  encountered 

2978  an  application  that  needs  to  tell  the  difference  must  set  errno  to  zero  before  the 

2979  call  and  check  it  if  NULL  is  returned.  Because  the  function  must  not  change 

2980  errno  in  case  (2)  and  must  set  it  to  a  nonzero  value  in  case  (1),  a  zero  errno  after  a 
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2981 


call  returning  NULL  indicates  end  of  directory,  otherwise  an  error. 


2985 

2986 


2983 

2984 


2982 


Routines  to  deal  with  this  problem  more  directly  were  proposed: 

int  derror  (dirp) 
dir  *dirp; 

void  clearderr  (dirp) 
dir  *dirp; 


2987  The  first  would  indicate  whether  an  error  had  occurred,  and  the  second  would 

2988  clear  the  error  indication.  The  simpler  method  involving  errno  was  adopted 

2989  instead  by  requiring  that  readdiri)  not  change  errno  when  end-of-directory  is 

2990  encountered. 

2991  Historical  implementations  include  two  more  functions: 

2992  long  telldir  (dirp) 

2993  DIR  *dirp; 

2994  void  seekdir  (dirp,  loc) 

2995  DIR  *dirp; 

2996  long  loc; 

2997  The  telldiri)  function  returns  the  current  location  associated  with  the  named 

2998  directory  stream. 

2999  The  seekdir ()  function  sets  the  position  of  the  next  readdiri)  operation  on  the 

3000  directory  stream.  The  new  position  reverts  to  the  one  associated  with  the  direc- 

3001  tory  stream  when  the  telldiri )  operation  was  performed. 

3002  These  functions  have  restrictions  on  their  use  related  to  implementation  details. 

3003  Their  capability  can  usually  be  accomplished  by  saving  a  filename  found  by  read- 

3004  diri)  and  later  using  rewinddiri )  and  a  loop  on  readdiri)  to  relocate  the  position 

3005  from  which  the  filename  was  saved.  Though  this  method  is  probably  slower  than 

3006  using  seekdiri )  and  telldiri ),  there  are  few  applications  in  which  the  capability  is 

3007  needed.  Furthermore,  directory  systems  that  are  implemented  using  technology 

3008  such  as  balanced  trees,  where  the  order  of  presentation  may  vary  from  access  to 

3009  access,  do  not  lend  themselves  well  to  any  concept  along  these  lines.  For  these 

3010  reasons,  seekdir ()  and  telldiri)  are  not  included  in  POSIX.l. 

3011  An  error  or  signal  indicating  that  a  directory  has  changed  while  open  was  con- 

3012  sidered  but  rejected. 

3013  B.5.1.3  Set  Position  of  Directory  Stream 

3014  The  seekdiri)  and  telldiri)  functions  were  proposed  for  inclusion  in  POSIX.l,  but 

3015  were  excluded  because  they  are  inherently  unreliable  when  all  the  possible  con- 

3016  forming  implementations  of  the  rest  of  POSIX.l  were  considered.  The  problem  is 

3017  that  returning  to  a  given  point  in  a  directory  is  quite  difficult  to  describe  formally, 

3018  in  spite  of  its  intuitive  appeal,  when  systems  that  used  B-trees,  hashing  functions, 

3019  or  other  similar  mechanisms  for  directory  search  are  considered. 

3020  Even  the  simple  goal  of  attempting  to  visit  each  directory  entry  that  is  unmodified 

3021  between  the  opendiri)  and  closediri)  calls  exactly  once  is  difficult  to  implement 

3022  reliably  in  the  face  of  directory  compaction  and  reorganization. 
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Since  the  primary  need  for  seekdir ()  and  telldirO  is  to  implement  file  tree  walks, 
and  since  such  a  function  is  likely  to  be  included  in  a  future  revision  of  POSIX.  1, 
and  since  in  that  more  constrained  context  it  appears  that  at  least  the  goal  of 
visiting  unmodified  nodes  exactly  once  can  be  achieved,  it  was  felt  that  waiting  for 
the  development  of  that  function  best  served  all  the  constituencies. 


B.5.2  Working  Directory 

B.5.2.1  Change  Current  Working  Directory 

The  chdirO  function  only  affects  the  working  directory  of  the  current  process. 

The  result  if  a  NULL  argument  is  passed  to  chdir( )  is  left  implementation  defined 
because  some  implementations  dynamically  allocate  space  in  that  case. 

B.5.2.2  Working  Directory  Pathname 

Since  the  maximum  pathname  length  is  arbitrary  unless  {PATH_MAX}  is  defined, 
an  application  generally  cannot  supply  a  buf  with  size  {{PATH_MAX}  +  1}. 

Having  getcwdO  take  no  arguments  and  instead  use  the  C  function  mallocO  to 
produce  space  for  the  returned  argument  was  considered.  The  advantage  is  that 
getcwdO  knows  how  big  the  working  directory  pathname  is  and  can  allocate  an 
appropriate  amount  of  space.  But  the  programmer  would  have  to  use  the  C  func¬ 
tion  free ()  to  free  the  resulting  object,  or  each  use  of  getcwdO  would  further 
reduce  the  available  memory.  Also,  mallocO  and  freeO  are  used  nowhere  else  in 
POSIX.1.  Finally,  getcwdO  is  taken  from  the  SVID  {B39},  where  it  has  the  two 
arguments  used  in  POSIX.1. 

The  older  function  getwdO  was  rejected  for  use  in  this  context  because  it  had  only 
a  buffer  argument  and  no  size  argument,  and  thus  had  no  way  to  prevent 
overwriting  the  buffer,  except  to  depend  on  the  programmer  to  provide  a  large 
enough  buffer. 

The  result  if  a  NULL  argument  is  passed  to  getcwdO  is  left  implementation 
defined  because  some  implementations  dynamically  allocate  space  in  that  case. 

If  a  program  is  operating  in  a  directory  where  some  (grand)parent  directory  does 
not  permit  reading,  getcwdO  may  fail,  as  in  most  implementations  it  must  read 
the  directory  to  determine  the  name  of  the  file.  This  can  occur  if  search,  but  not 
read,  permission  is  granted  in  an  intermediate  directory,  or  if  the  program  is 
placed  in  that  directory  by  some  more  privileged  process  (e.g.,  login).  Including 
this  error,  [EACCES],  makes  the  reporting  of  the  error  consistent  and  warns  the 
application  writer  that  getcwdO  can  fail  for  reasons  beyond  the  control  of  the 
application  writer  or  user.  Some  implementations  can  avoid  this  occurrence  [e.g., 
by  implementing  getcwdi )  using  pwd,  where  pwd  is  a  set-user-root  process!,  thus 
the  error  was  made  optional. 

Because  POSIX.1  permits  the  addition  of  other  errors,  this  would  be  a  common 
addition  and  yet  one  that  applications  could  not  be  expected  to  deal  with  without 
this  addition. 
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3063  Some  current  implementations  use  {PATH_MAX}+2  bytes.  These  will  have  to  be 

3064  changed.  Many  of  those  same  implementations  also  may  not  diagnose  the 

3065  [ERANGEl  error  properly  or  deal  with  a  common  bug  having  to  do  with  newline  in 

3066  a  directory  name  (the  fix  to  which  is  essentially  the  same  as  the  fix  for  using  +1 

3067  bytes),  so  this  is  not  a  severe  hardship. 

3068  B.5.2.3  Change  Process’s  Root  Directory  | 

3069  The  chroot ()  function  was  excluded  from  POSIX.l  on  the  basis  that  it  was  not  use-  | 

3070  ful  to  portable  applications.  In  particular,  creating  an  environment  in  which  an  | 

3071  application  could  run  after  executing  a  chrootO  call  is  well  beyond  the  current  | 

3072  scope  of  POSIX.l. 

3073  B.5.3  General  File  Creation 

3074  Because  there  is  no  portable  way  to  specify  a  value  for  the  argument  indicating 

3075  the  file  mode  bits  (except  zero),  <sys/stat.h>  is  included  with  the  functions 

3076  that  reference  mode  bits. 

3077  B.5.3. 1  Open  a  File 

3078  Except  as  specified  in  POSIX.l,  the  flags  allowed  in  oflag  are  not  mutually 

3079  exclusive  and  any  number  of  them  may  be  used  simultaneously. 

3080  Some  implementations  permit  opening  FIFOs  with  0_RDWR.  Since  FIFOs  could 

3081  be  implemented  in  other  ways,  and  since  two  file  descriptors  can  be  used  to  the 

3082  same  effect,  this  possibility  is  left  as  undefined. 

3083  See  B.4.2.3  about  the  group  of  a  newly  created  file. 

3084  The  use  of  open( )  to  create  a  regular  file  is  preferable  to  the  use  of  creat( )  because 

3085  the  latter  is  redundant  and  included  only  for  historical  reasons. 

3086  The  use  of  the  0_TRUNC  flag  on  FIFOs  and  directories  [pipes  cannot  be  open()-e  d] 

3087  must  be  permissible  without  unexpected  side  effects  [e.g.,  creati)  on  a  FIFO  must 

3088  not  remove  data].  Because  terminal  special  files  might  have  type-ahead  data  | 

3089  stored  in  the  buffer,  0_TRUNC  should  not  affect  their  content,  particularly  if  a  | 

3090  program  that  normally  opens  a  regular  file  should  open  the  current  controlling  | 

3091  terminal  instead.  Other  file  types,  particularly  implementation-defined  ones,  are 

3092  left  implementation  defined. 

3093  Implementations  may  deny  access  and  return  [EACCES]  for  reasons  other  than 

3094  just  those  listed  in  the  [EACCES]  definition. 

3095  The  0_NOCTTY  flag  was  added  to  allow  applications  to  avoid  unintentionally 

3096  acquiring  a  controlling  terminal  as  a  side  effect  of  opening  a  terminal  file. 

3097  POSIX.1  does  not  specify  how  a  controlling  terminal  is  acquired,  but  it  allows  an 

3098  implementation  to  provide  this  on  open  ()  if  the  0_NOCTTY  flag  is  not  set  and 

3099  other  conditions  specified  in  7. 1.1.3  are  met.  The  0_NOCTTY  flag  is  an  effective 

3100  no-op  if  the  file  being  opened  is  not  a  terminal  device. 

3101  In  historical  implementations  the  value  of  0_RDONLY  is  zero.  Because  of  that,  it 

3102  is  not  possible  to  detect  the  presence  of  0_RDONLY  and  another  option.  Future 
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3103  implementations  should  encode  0_RD0NLY  and  0_WR0NLY  as  bit  flags  so  that: 

3104  0_RD0NLY  |  0_WR0NLY  ==  O.RDWR 

3105  See  the  rationale  for  the  change  from  0_NDELAY  to  0_N0NBL0CK  in  B.6. 

3106  B.5.3.2  Create  a  New  File  or  Rewrite  an  Existing  One 

3107  The  creati)  function  is  redundant.  Its  services  are  also  provided  by  the  open() 

3108  function.  It  has  been  included  primarily  for  historical  purposes  since  many  exist- 

3109  ing  applications  depend  on  it.  It  is  best  considered  a  part  of  the  C  binding  rather 

3110  than  a  function  that  should  be  provided  in  other  languages. 

3111  B.5.3.3  Set  File  Creation  Mask 

3112  Unsigned  argument  and  return  types  for  umask  ()  were  proposed.  The  return 

3113  type  and  the  argument  were  both  changed  to  modejt. 

3114  Historical  implementations  have  made  use  of  additional  bits  in  cmask  for  their 
3H5  implementation-specific  purposes.  The  addition  of  the  text  that  the  meaning  of 
3H6  other  bits  of  the  field  are  implementation  defined  permits  these  implementations 

3117  to  conform  to  POSIX.  1. 

3118  B.5.3.4  Link  to  a  File 

3119  See  B. 2.2.2. 

3120  Linking  to  a  directory  is  restricted  to  the  super-user  in  most  historical  implemen- 

3121  tations  because  this  capability  may  produce  loops  in  the  file  hierarchy  or  other- 

3122  wise  corrupt  the  file  system.  POSIX.l  continues  that  philosophy  by  prohibiting 

3123  link ()  and  unlink  ()  from  doing  this.  Other  functions  could  do  it  if  the  implemen- 

3124  tor  designed  such  an  extension. 

3125  Some  historical  implementations  allow  linking  of  files  on  different  file  systems. 

3126  Wording  was  added  to  explicitly  allow  this  optional  behavior.  Symbolic  links  are  | 

3127  not  discussed  by  POSIX.  1.  The  exception  for  cross-file  system  links  is  intended  to  | 

3128  apply  only  to  links  that  are  programmatically  indistinguishable  from  “hard”  links.  | 

3129  B.5.4  Special  File  Creation 

3130  B.5.4.1  Make  a  Directory 

3131  See  B.2.5. 

3132  The  mkdir()  function  originated  in  4.2BSD  and  was  added  to  System  V  in 

3133  Release  3.0. 

3134  4.3BSD  detects  [ENAMETQOLONG]. 

3135  See  B.4.2.3  about  the  group  of  a  newly  created  directory. 
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3136  B.5.4.2  Make  a  FIFO  Special  File 

3137  The  syntax  of  this  routine  is  intended  to  maintain  compatibility  with  historical  | 

3138  implementations  of  mknod{).  The  latter  function  was  included  in  the  1984  \ 

3139  /usr /group  Standard  {B59},  but  only  for  use  in  creating  FIFO  special  files.  The 

3140  mknod()  function  was  excluded  from  POSIX.1  as  implementation  defined  and 

3141  replaced  by  mkdir( )  and  mkfifo( ). 

3142  See  B.4.2.3  about  the  group  of  a  newly  created  FIFO. 

3143  B.5.5  File  Removal 

3144  The  rmdir()  and  rename ()  functions  originated  in  4.2BSD,  and  they  used 

3145  [ENOTEMPTY]  for  the  condition  when  the  directory  to  be  removed  does  not  exist 

3146  or  new  already  exists.  When  the  1984  /usr /group  Standard  {B59}  was  published, 

3147  it  contained  [EEXIST]  instead.  When  these  functions  were  adopted  into  System  V,  | 

3148  the  1984  /usr /group  Standard  {B59}  was  used  as  a  reference.  Therefore,  several  | 

3149  existing  applications  and  implementations  support/use  both  forms,  and  no  agree-  | 

3150  ment  could  be  reached  on  either  value.  All  implementations  are  required  to  sup-  | 

3151  ply  both  [EEXIST]  and  [ENOTEMPTY]  in  <errno.h>  with  distinct  values  so  that 

3152  applications  can  use  both  values  in  C  language  case  statements. 

3153  B.5.5.1  Remove  Directory  Entries 

3154  Unlinking  a  directory  is  restricted  to  the  super-user  in  many  historical  implemen- 

3155  tations  for  reasons  given  in  B.5.3.4.  But  see  B.5.5.3. 

3156  The  meaning  of  [EBUSY]  in  historical  implementations  is  “mount  point  busy.” 

3157  Since  POSIX.1  does  not  cover  the  system  administration  concepts  of  mounting  and 

3158  unmounting,  the  description  of  the  error  was  changed  to  “resource  busy.”  (This 

3159  meaning  is  used  by  some  device  drivers  when  a  second  process  tries  to  open  an 

3160  exclusive  use  device.)  The  wording  is  also  intended  to  allow  implementations  to 

3161  refuse  to  remove  a  directory  if  it  is  the  root  or  current  working  directory  of  any 

3162  process. 

3163  B.5.5.2  Remove  a  Directory 

3164  See  also  B.5.5  and  B.5.5.1. 

3165  B.5.5.3  Rename  a  File 

3166  This  rename  ()  function  is  equivalent  for  regular  files  to  that  defined  by  the 

3167  C  Standard  {2}.  Its  inclusion  here  expands  that  definition  to  include  actions  on 

3168  directories  and  specifies  behavior  when  the  new  parameter  names  a  file  that 

3169  already  exists.  That  specification  requires  that  the  action  of  the  function  be 

3170  atomic. 

3171  One  of  the  reasons  for  introducing  this  function  was  to  have  a  means  of  renaming 

3172  directories  while  permitting  implementations  to  prohibit  the  use  of  link  ()  and 

3173  unlink ()  with  directories,  thus  constraining  links  to  directories  to  those  made  by 

3174  mkdir{). 
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3175  The  specification  that  if  old  and  new  refer  to  the  same  file  describes  existing, 

3176  although  undocumented,  4.3BSD  behavior.  It  is  intended  to  guarantee  that: 

3177  rename  ("x",  "x"); 

3178  does  not  remove  the  file. 

3179  Renaming  dot  or  dot-dot  is  prohibited  in  order  to  prevent  cyclical  file  system 

3180  paths. 

3181  See  also  the  descriptions  of  [ENOTEMPTY]  and  [ENAMETOOLONG]  in  B.5.5  and 

3182  [EBUSYl  in  B.5.5.1.  For  a  discussion  of  [EXDEV],  see  B.5. 3.4. 

3183  B.5.6  File  Characteristics 

3184  The  ustat ()  function,  which  appeared  in  the  1984  /usr/ group  Standard  {B59}  and 

3185  is  still  in  the  SVID  {B39},  was  excluded  from  POSIX.1  because  it  is: 

3186  —  Not  reliable.  The  amount  of  space  available  can  change  between  the  time 

3187  the  call  is  made  and  the  time  the  calling  process  attempts  to  use  it. 

3188  —  Not  required.  The  only  known  program  that  uses  it  is  the  text  editor  ed. 

3189  —  Not  readily  extensible  to  networked  systems. 

3190  B.5.6.1  File  Characteristics:  Header  and  Data  Structure 

3191  See  B.2.5. 

3192  A  conforming  C  language  application  must  include  <sys/stat .  h>  for  functions 

3193  that  have  arguments  or  return  values  of  type  modejt,  so  that  symbolic  values  for 

3194  that  type  can  be  used.  An  alternative  would  be  to  require  that  these  constants 

3195  are  also  defined  by  including  <sy s/types  .  h>. 

3196  The  S_ISUID  and  S_ISGID  bits  may  be  cleared  on  any  write,  not  just  on  open(),  as 

3197  some  historical  implementations  do  it. 

3198  System  calls  that  update  the  time  entry  fields  in  the  stat  structure  must  be  docu- 

3199  mented  by  the  implementors.  POSIX.1  conforming  systems  should  not  update  the 

3200  time  entry  fields  for  functions  listed  in  POSIX.1  unless  the  standard  requires  that 

3201  they  do,  except  in  the  case  of  documented  extensions  to  the  standard. 

3202  Note  that  stjdev  must  be  unique  within  a  Local  Area  Network  (LAN)  in  a  “system” 

3203  made  up  of  multiple  computers’  file  systems  connected  by  a  LAN. 

3204  Networked  implementations  of  a  POSIX.1  system  must  guarantee  that  all  files 

3205  visible  within  the  file  tree  (including  parts  of  the  tree  that  may  be  remotely 

3206  mounted  from  other  machines  on  the  network)  on  each  individual  processor  are 

3207  uniquely  identified  by  the  combination  of  the  stj.no  and  stjdev  fields. 

3208  B.5.6.2  Get  File  Status 

3209  The  intent  of  the  paragraph  describing  “additional  or  alternate  file  access  control 

3210  mechanisms”  is  to  allow  a  secure  implementation  where  a  process  with  a  label 

3211  that  does  not  dominate  the  file’s  label  cannot  perform  a  stat ()  function.  This  is 

3212  not  related  to  read  permission;  a  process  with  a  label  that  dominates  the  file’s 
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label  will  not  need  read  permission.  An  implementation  that  supports  write-up 
operations  could  fail  fstat ()  function  calls  even  though  it  has  a  valid  file  descriptor 
open  for  writing. 

B.5.6.3  File  Accessibility 

In  early  drafts  of  POSIX.l,  some  inadequacies  in  the  access ()  function  led  to  the  | 
creation  of  an  e access ()  function  because:  | 

(1)  Historical  implementations  of  access  ()  do  not  test  file  access  correctly 
when  the  process’s  real  user  ID  is  super-user.  In  particular,  they  always 
return  zero  when  testing  execute  permissions  without  regard  to  whether 
the  file  is  executable. 

(2)  The  super-user  has  complete  access  to  all  files  on  a  system.  As  a  conse¬ 
quence,  programs  started  by  the  super-user  and  switched  to  the  effective 
user  ID  with  lesser  privileges  cannot  use  access  ()  to  test  their  file  access 
permissions. 

However,  the  historical  model  of  eaccess ()  does  not  resolve  problem  (1),  so  POSIX.l  | 
now  allows  access  ()  to  behave  in  the  desired  way  because  several  implementa¬ 
tions  have  corrected  the  problem.  It  was  also  argued  that  problem  (2)  is  more 
easily  solved  by  using  open{),  chdir (),  or  one  of  the  exec  functions  as  appropriate 
and  responding  to  the  error,  rather  than  creating  a  new  function  that  would  not 
be  as  reliable.  Therefore,  eaccessO  was  taken  back  out  of  POSIX.l. 

Secure  implementations  will  probably  need  an  extended  accessi  )-like  function,  but 
there  were  not  enough  of  the  requirements  to  define  it  yet.  This  could  be  pro¬ 
posed  as  an  extension  for  a  future  amendment  to  POSIX.l. 

The  sentence  concerning  appropriate  privileges  and  execute  permission  bits 
reflects  the  two  possibilities  implemented  by  historical  implementations  when 
checking  super-user  access  for  X_OK. 

B.5.6.4  Change  File  Modes 

POSIX.1  specifies  that  the  S_ISGID  bit  is  cleared  by  chmodi)  on  a  regular  file 
under  certain  conditions.  This  is  specified  on  the  assumption  that  regular  files 
may  be  executed,  and  the  system  should  prevent  users  from  making  executable 
setgid  files  perform  with  privileges  that  the  caller  does  not  have.  On  implementa¬ 
tions  that  support  execution  of  other  file  types,  the  S_ISGID  bit  should  be  cleared 
for  those  file  types  under  the  same  circumstances. 

Implementations  that  use  the  S_ISUID  bit  to  indicate  some  other  function  (for 
example,  mandatory  record  locking)  on  nonexecutable  files  need  not  clear  this  bit 
on  writing.  They  should  clear  the  bit  for  executable  files  and  any  other  cases 
where  the  bit  grants  special  powers  to  processes  that  change  the  file  contents. 
Similar  comments  apply  to  the  S_ISGID  bit. 
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B.5.6.5  Change  Owner  and  Group  of  File 

System  III  and  System  V  allow  a  user  to  give  away  files;  that  is,  the  owner  of  a  file 
may  change  its  user  ID  to  anything.  This  is  a  serious  problem  for  implementa¬ 
tions  that  are  intended  to  meet  government  security  regulations.  Version  7  and 
4.3BSD  permit  only  the  super-user  to  change  the  user  ID  of  a  file.  Some  govern¬ 
ment  agencies  (usually  not  ones  concerned  directly  with  security)  find  this  limita¬ 
tion  too  confining.  POSIX.  1  uses  “may”  to  permit  secure  implementations  while 
not  disallowing  System  V. 

System  III  and  System  V  allow  the  owner  of  a  file  to  change  the  group  ID  to  any¬ 
thing.  Version  7  permits  only  the  super-user  to  change  the  group  ID  of  a  file. 
4.3BSD  permits  the  owner  to  change  the  group  ID  of  a  file  to  its  effective  group  ID 
or  to  any  of  the  groups  in  the  list  of  supplementary  group  IDs,  but  to  no  others. 

Although  chownO  can  be  used  on  some  systems  by  the  file  owner  to  change  the 
owner  and  group  to  any  desired  values,  the  only  portable  use  of  this  function  is  to 
change  the  group  of  a  file  to  the  effective  GID  of  the  calling  process  or  to  a  member 
of  its  group  set. 

The  decision  to  require  that,  for  nonprivileged  processes,  the  S_ISUID  and 
S_ISGID  bits  be  cleared  on  regular  files,  but  only  may  be  cleared  on  nonregular 
files,  was  to  allow  plans  for  using  these  bits  in  implementation-specified  manners 
on  directories.  Similar  cases  could  be  made  for  other  file  types,  so  POSIX.l  does 
not  require  that  these  bits  be  cleared  except  on  regular  files.  As  these  cases  arise, 
the  system  implementors  will  have  to  determine  whether  these  features  enable 
any  security  loopholes  and  specify  appropriate  restrictions.  If  the  implementation 
supports  executing  any  file  types  other  than  regular  files,  the  S_ISUID  and 
S_ISGID  bits  should  be  cleared  for  those  file  types  in  the  same  way  as  they  are  on 
regular  files. 

B.5.6.6  Set  File  Access  and  Modification  Times 

The  actime  structure  member  must  be  present  so  that  an  application  may  set  it, 
even  though  an  implementation  may  ignore  it  and  not  change  the  access  time  on 
the  file.  If  an  application  intends  to  leave  one  of  the  times  of  a  file  unchanged 
while  changing  the  other,  it  should  use  stat{)  to  retrieve  the  file’s  st_atime  and 
stjntime  parameters,  set  actime  and  modtime  in  the  buffer,  and  change  one  of 
them  before  making  the  utime  ()  call. 


B.5.7  Configurable  Pathname  Variables 

When  the  run-time  facility  described  in  B.4.8  was  designed,  it  was  realized  that 
some  variables  change  depending  on  the  file  system.  For  example,  it  is  quite 
feasible  for  a  system  to  have  two  varieties  of  file  systems  mounted:  a  System  V  | 
file  system  and  a  BSD  “Fast  File  System.”  | 

If  limited  to  strictly  compile-time  features,  no  application  that  was  widely  distri¬ 
buted  in  executable  binary  form  could  rely  on  more  than  14  bytes  in  a  pathname 
component,  as  that  is  the  minimum  published  for  {NAME_MAX}  in  POSIX.  1.  The 
pathconfi )  function  allows  the  application  to  take  advantage  of  the  most  liberal 
file  system  available  at  run-time.  In  many  BSD-based  systems,  255  bytes  are  | 
allowed  for  pathname  components. 
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These  values  are  potentially  changeable  at  the  directory  level,  not  just  at  the  file 
system.  And,  unlike  the  overall  system  variables,  there  is  no  guarantee  that 
these  might  not  change  during  program  execution. 

B.5.7.1  Get  Configurable  Pathname  Variables 

The  pathconfO  function  was  proposed  immediately  after  the  sysconfO  function 
when  it  was  realized  that  some  configurable  values  may  differ  across  file  system, 
directory,  or  device  boundaries. 

For  example,  {NAME_MAX}  frequently  changes  between  System  V  and  BSD-based 
file  systems;  System  V  uses  a  maximum  of  14,  BSD  255.  On  an  implementation  | 
that  provided  both  types  of  file  systems,  an  application  would  be  forced  to  limit  all 
pathname  components  to  14  bytes,  as  this  would  be  the  value  specified  in 
< limits  .h>  on  such  a  system. 

Therefore,  various  useful  values  can  be  queried  on  any  pathname  or  file  descrip¬ 
tor,  assuming  that  the  appropriate  permissions  are  in  place. 

The  value  returned  for  the  variable  {PATH_MAX}  indicates  the  longest  relative 
pathname  that  could  be  given  if  the  specified  directory  is  the  process’s  current 
working  directory.  A  process  may  not  always  be  able  to  generate  a  name  that 
long  and  use  it  if  a  subdirectory  in  the  pathname  crosses  into  a  more  restrictive 
file  system. 

The  value  returned  for  the  variable  {_POSIX_CHOWN_RESTRICTED}  also  applies 
to  directories  that  do  not  have  file  systems  mounted  on  them.  The  value  may 
change  when  crossing  a  mount  point,  so  applications  that  need  to  know  should 
check  for  each  directory.  [An  even  easier  check  is  to  try  the  chownO  function  and 
look  for  an  error  in  case  it  happens.! 

Unlike  the  values  returned  by  sysconfO,  the  pathname-oriented  variables  are 
potentially  more  volatile  and  are  not  guaranteed  to  remain  constant  throughout 
the  process’s  lifetime.  For  example,  in  between  two  calls  to  pathconfO,  the  file 
system  in  question  may  have  been  unmounted  and  remounted  with  different 
characteristics. 

Also  note  that  most  of  the  errors  are  optional.  If  one  of  the  variables  always  has 
the  same  value  on  an  implementation,  the  implementation  need  not  look  at  path 
or  fddes  to  return  that  value  and  is,  therefore,  not  required  to  detect  any  of  the 
errors  except  the  meaning  of  [EINVAL]  that  indicates  that  the  value  of  name  is  not 
valid  for  that  variable. 

If  the  value  of  any  of  the  limits  described  in  2.8.4  or  2.8.5  are  indeterminate  (logi¬ 
cally  infinite),  they  will  not  be  defined  in  <limits.h>  and  the  pathconfO  and 
fpathconfO  functions  will  return  -1  without  changing  errno.  This  can  be  dis¬ 
tinguished  from  the  case  of  giving  an  unrecognized  name  argument  because  errno 
will  be  set  to  [EINVAL]  in  this  case. 

Since  —1  is  a  valid  return  value  for  the  pathconfO  and  fpathconfO  functions, 
applications  should  set  errno  to  zero  before  calling  them  and  check  errno  only  if 
the  return  value  is  -1. 
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B.6  Input  and  Output  Primitives 

System  III  and  System  V  have  included  a  flag,  0_NDELAY,  to  mark  file  descrip¬ 
tors  so  that  user  processes  would  not  block  when  doing  I/O  to  them.  If  the  flag  is 
set,  a  read ()  or  writeO  call  that  would  otherwise  need  to  block  for  data  returns  a 
value  of  zero  instead.  But  a  read ()  call  also  returns  a  value  of  zero  on  end-of-file, 
and  applications  have  no  way  to  distinguish  between  these  two  conditions. 

BSD  systems  support  a  similar  feature  through  a  flag  with  the  same  name,  but 
somewhat  different  semantics.  The  flag  applies  to  all  users  of  a  file  (or  socket) 
rather  than  only  to  those  sharing  a  file  descriptor.  The  BSD  interface  provides  a 
solution  to  the  problem  of  distinguishing  between  a  blocking  condition  and  an 
end-of-file  condition  by  returning  an  error,  [EWOULDBLOCK],  on  a  blocking 
condition. 

The  1984  /usr /group  Standard  {B59}  includes  an  interface  with  some  features 
from  both  System  III/V  and  BSD.  The  overall  semantics  are  that  it  applies  only  to  | 
a  file  descriptor.  However,  the  return  indication  for  a  blocking  condition  is  an 
error,  [E  AG  AIN].  This  was  the  starting  point  for  POSIX.l. 

The  problem  with  the  1984  /usr /group  Standard  {B59}  is  that  it  does  not  allow 
compatibility  with  existing  applications.  An  implementation  cannot  both  conform 
to  that  standard  and  support  applications  written  for  existing  System  V  or  BSD  | 
systems.  Several  changes  have  been  considered  address  this  issue.  These 
include: 

(1)  No  change  (from  1984  /usr /group  Standard  {B59}) 

(2)  Changing  to  System  III/V  semantics 

(3)  Changing  to  BSD  semantics 

(4)  Broadening  POSIX.l  to  allow  conforming  implementation  a  choice  among 
these  semantics 

(5)  Changing  the  name  of  the  flag  from  0_NDELAY 

(6)  Changing  to  System  III/V  semantics  and  providing  a  new  call  to  distin¬ 
guish  between  blocking  and  end-of-file  conditions 

Alternative  (5)  was  the  consensus  choice.  The  new  name  is  0_NONBLOCK.  This  | 
alternative  allows  a  conforming  implementation  to  provide  backward  compatibil¬ 
ity  at  the  source  and/or  object  level  with  either  System  III/V  or  BSD  systems  (but  | 
POSIX.l  does  not  require  or  even  suggest  that  this  be  done).  It  also  allows  a  Con¬ 
forming  POSIX.  1  Application  Using  Extensions  the  functionality  to  distinguish 
between  blocking  and  end-of-file  conditions,  and  to  do  so  in  as  simple  a  manner  as 
any  of  the  alternatives.  The  greatest  shortcoming  was  that  it  forces  all  existing  | 
System  III/V  and  BSD  applications  that  use  this  facility  to  be  modified  in  order  to  | 
strictly  conform  to  POSIX.1.  This  same  shortcoming  applies  to  (1)  and  (4)  as  well, 
and  it  applies  to  one  group  of  applications  for  (2),  (3),  and  (6). 

Systems  may  choose  to  implement  both  0_NDELAY  and  0_NONBLOCK,  and  there 
is  no  conflict  as  long  as  an  application  does  not  turn  both  flags  on  at  the  same 
time. 
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3379  See  also  the  discussion  of  scope  in  B. 6.5.1. 

3380  B.6.1  Pipes 

3381  An  implementation  that  fails  write()  operations  on  fildesi 0]  or  read()s  on  fildesY  1] 

3382  is  not  required.  Historical  implementations  (Version  7  and  System  V)  return  the 

3383  error  [EBADF]  in  such  cases.  This  allows  implementations  to  set  up  a  second  pipe 

3384  for  full  duplex  operation  at  the  same  time.  A  conforming  application  that  uses  the 

3385  pipe ()  function  as  described  in  POSIX.1  will  succeed  whether  this  second  pipe  is 

3386  present  or  not. 

3387  B.6.1. 1  Create  an  Inter-Process  Channel 

3388  The  wording  carefully  avoids  using  the  verb  “to  open”  in  order  to  avoid  any  impli- 

3389  cation  of  use  of  open  ( ). 

3390  See  also  B.6.4.2. 

3391  B.6.2  File  Descriptor  Manipulation 

3392  B.6.2. 1  Duplicate  an  Open  File  Descriptor 

3393  The  dup  ()  and  dup2( )  functions  are  redundant.  Their  services  are  also  provided 

3394  by  the  fcntl{)  function.  They  have  been  included  in  POSIX.1  primarily  for  histori- 

3395  cal  reasons,  since  many  existing  applications  use  them. 

3396  While  the  brief  code  segment  shown  is  very  similar  in  behavior  to  dup2(),  a  con- 

3397  forming  implementation  based  on  other  functions  defined  by  POSIX.1  is 

3398  significantly  more  complex.  Least  obvious  is  the  possible  effect  of  a  signal- 

3399  catching  function  that  could  be  invoked  between  steps  and  allocate  or  deallocate 

3400  file  descriptors.  This  could  be  avoided  by  blocking  signals. 

3401  The  dup2()  function  is  not  marked  obsolescent  because  it  presents  a  type-safe  ver- 

3402  sion  of  functionality  provided  in  a  type-unsafe  version  by  fcntl().  It  is  used  in  the 

3403  current  draft  of  the  Ada  binding  to  POSIX.1. 

3404  The  dup2()  function  is  not  intended  for  use  in  critical  regions  as  a  synchroniza- 

3405  tion  mechanism. 

3406  In  the  description  of  [EBADF],  the  case  of  fildes  being  out  of  range  is  covered  by 

3407  the  given  case  of  fildes  not  being  valid.  The  descriptions  for  fildes  and  fldes2  are 

3408  different  because  the  only  kind  of  invalidity  that  is  relevant  for  fildes2  is  whether 

3409  it  is  out  of  range;  that  is,  it  does  not  matter  whether  fildes2  refers  to  an  open  file 

3410  when  the  dup2{)  call  is  made. 

3411  If  fildes2  is  a  valid  file  descriptor,  it  shall  be  closed,  regardless  of  whether  the 

3412  function  returns  an  indication  of  success  or  failure,  unless  fildes2  is  equal  to 

3413  fildes. 
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B.6.3  File  Descriptor  Deassignment 
B.6.3.1  Close  a  File 

Once  a  file  is  closed,  the  file  descriptor  no  longer  exists,  since  the  integer 
corresponding  to  it  no  longer  refers  to  a  file. 

The  use  of  interruptible  device  close  routines  should  be  discouraged  to  avoid  prob¬ 
lems  with  the  implicit  closes  of  file  descriptors  by  exec  and  exit{).  POSIX.1  only 
intends  to  permit  such  behavior  by  specifying  the  [EINTR]  error  case. 


B.6.4  Input  and  Output 

The  use  of  I/O  with  large  byte  counts  has  always  presented  problems.  Ideas  such  | 
as  Iread ()  and  Iwrite ()  (using  and  returning  longs )  were  considered  at  one  time.  | 
The  current  solution  is  to  use  abstract  types  on  the  C  Standard  {2}  interface  to  | 
read ()  and  write()  (and  not  to  discuss  common  usage).  The  abstract  types  can  be  | 
declared  so  that  existing  interfaces  work,  but  can  also  be  declared  so  that  larger  | 
types  can  be  represented  in  future  implementations.  It  is  presumed  that  what-  | 
ever  constraints  limit  the  maximum  range  of  sizejt  also  limit  portable  I/O  requests  | 
to  the  same  range.  POSIX.1  also  limits  the  range  further  by  requiring  that  the  | 
byte  count  be  limited  so  that  a  signed  return  value  remains  meaningful.  Since  | 
the  return  type  is  also  a  (signed)  abstract  type,  the  byte  count  can  be  defined  by  | 
the  implementation  to  be  larger  than  an  int  can  hold.  | 

POSIX.1  requires  that  no  action  be  taken  when  nbyte  is  zero.  This  is  not  intended 
to  take  precedence  over  detection  of  errors  (such  as  invalid  buffer  pointers  or  file 
descriptors).  This  is  consistent  with  the  rest  of  POSIX.1,  but  the  phrasing  here 
could  be  misread  to  require  detection  of  the  zero  case  before  any  other  errors.  A 
value  of  zero  is  to  be  considered  a  correct  value,  for  which  the  semantics  are  a 
no-op. 

There  were  recommendations  to  add  format  parameters  to  read{ )  and  write ()  in 
order  to  handle  networked  transfers  among  heterogeneous  file  system  and  base 
hardware  types.  Such  a  facility  may  be  required  for  support  by  the  OSI  presenta¬ 
tion  of  layer  services.  However,  it  was  determined  that  this  should  correspond  | 
with  similar  C  Language  facilities,  and  that  is  beyond  the  scope  of  POSIX.1.  The  | 
concept  was  suggested  to  the  developers  of  the  C  Standard  {2}  for  their  considera-  | 
tion  as  a  possible  area  for  future  work.  | 

In  4.3BSD,  a  readO  or  write ()  that  is  interrupted  by  a  signal  before  transferring 
any  data  does  not  by  default  return  an  [EINTR]  error,  but  is  restarted.  In  4.2BSD, 
4.3BSD,  and  the  Eighth  Edition  there  is  an  additional  function,  select (),  whose 
purpose  is  to  pause  until  specified  activity  (data  to  read,  space  to  write,  etc.)  is 
detected  on  specified  file  descriptors.  It  is  common  in  applications  written  for 
those  systems  for  selectO  to  be  used  before  read ()  in  situations  (such  as  keyboard 
input)  where  interruption  of  I/O  due  to  a  signal  is  desired.  But  this  approach  does 
not  conform,  because  selectO  is  not  in  POSIX.1.  4.3BSD  semantics  can  be  provided 
by  extensions  to  POSIX.1. 

POSIX.1  permits  readO  and  writeO  to  return  the  number  of  bytes  successfully 
transferred  when  interrupted  by  an  error.  This  is  not  simply  required  because  it 
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was  not  done  by  Version  7,  System  III,  or  System  V,  and  because  some  hardware 
may  not  be  capable  of  returning  information  about  partial  transfers  if  a  device 
operation  is  interrupted.  Unfortunately,  this  does  make  writing  a  Conforming 
POSIX.1  Application  more  difficult  in  circumstances  where  this  could  occur. 

Requiring  this  behavior  does  not  address  the  situation  of  pipelined  buffers,  such 
as  might  be  found  in  streaming  tape  drives  or  other  devices  that  read  ahead  of  the 
actual  requests.  The  signal  interruption  will  often  indicate  an  exceptional  condi¬ 
tion  and  flush  all  buffers.  Thus,  the  amount  read  from  the  device  may  be  dif¬ 
ferent  from  the  amount  transferred  to  the  application. 

The  issue  of  which  files  or  file  types  are  interruptible  is  considered  an  implemen¬ 
tation  design  issue.  This  is  often  affected  primarily  by  hardware  and  reliability 
issues. 

There  are  no  references  to  actions  taken  following  an  “unrecoverable  error.”  It  is 
considered  beyond  the  scope  of  POSIX.1  to  describe  what  happens  in  the  case  of 
hardware  errors. 

B.6.4.1  Read  from  a  File 

POSIX.1  does  not  specify  the  value  of  the  file  offset  after  an  error  is  returned; 
there  are  too  many  cases.  For  programming  errors,  such  as  [EBADF],  the  concept 
is  meaningless  since  no  file  is  involved.  For  errors  that  are  detected  immediately, 
such  as  [EAGAINl,  clearly  the  pointer  should  not  change.  After  an  interrupt  or 
hardware  error,  however,  an  updated  value  would  be  very  useful  and  is  the 
behavior  of  many  implementations. 

Note  that  a  read()  of  zero  bytes  does  not  modify  stjatime.  A  read()  that  requests  | 
more  than  zero  bytes,  but  returns  zero,  does  modify  st_atime.  \ 

B.6.4.2  Write  to  a  File 

An  attempt  to  write  to  a  pipe  or  FIFO  has  several  major  characteristics: 

Atomic/nonatomic 

A  write  is  atomic  if  the  whole  amount  written  in  one  operation  is  not 
interleaved  with  data  from  any  other  process.  This  is  useful  when  there 
are  multiple  writers  sending  data  to  a  single  reader.  Applications  need 
to  know  how  large  a  write  request  can  be  expected  to  be  performed  atomi¬ 
cally.  This  maximum  is  called  {PIPE_BUF}.  POSIX.1  does  not  say 
whether  write  requests  for  more  than  {PIPE_BUF}  bytes  will  be  atomic, 
but  requires  that  writes  of  {PIPE_BUF}  or  fewer  bytes  shall  be  atomic. 

Blocking/immediate 

Blocking  is  only  possible  with  0_NONBLOCK  clear.  If  there  is  enough 
space  for  all  the  data  requested  to  be  written  immediately,  the  implemen¬ 
tation  should  do  so.  Otherwise,  the  process  may  block;  that  is,  pause 
until  enough  space  is  available  for  writing.  The  effective  size  of  a  pipe  or 
FIFO  (the  maximum  amount  that  can  be  written  in  one  operation  without 
blocking)  may  vary  dynamically,  depending  on  the  implementation,  so  it 
is  not  possible  to  specify  a  fixed  value  for  it. 
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Complete/partial/deferred 
A  write  request, 

int  fildes; 
size_t  nbyte; 
ssize_t  ret; 
char  *buf; 


ret  =  write  (fildes,  buf,  nbyte) ; 

may  return 

complete:  ret  =  nbyte 
partial:  ret  <  nbyte 

This  shall  never  happen  if  nbyte  <  {PIPE_BUF}.  If  it  does 
happen  (with  nbyte  >  {PIPE_BUF}),  POSIX.  1  does  not 
guarantee  atomicity,  even  if  ret  <  {PIPE_BUF},  because 
atomicity  is  guaranteed  according  to  the  amount  requested, 
not  the  amount  written. 

deferred:  ret  =  -1,  errno  =  [EAGAIN] 

This  error  indicates  that  a  later  request  may  succeed.  It 
does  not  indicate  that  it  shall  succeed,  even  if  nbyte  < 
{PIPE_BUF},  because  if  no  process  reads  from  the  pipe  or 
FIFO,  the  write  will  never  succeed.  An  application  could 
usefully  count  the  number  of  times  [EAGAIN]  is  caused  by  a 
particular  value  of  nbyte  >  {PIPE_BUF}  and  perhaps  do 
later  writes  with  a  smaller  value,  on  the  assumption  that 
the  effective  size  of  the  pipe  may  have  decreased. 

Partial  and  deferred  writes  are  only  possible  with  0_NONBLOCK  set. 


The  relations  of  these  properties  are  shown  in  the  following  tables. 


Write  to  a  Pipe  or  FIFO  with  0 NONBLOCK  clear 

Immediately 

Writable: 

None 

Some 

nbyte 

nbyte  < 
{PIPE.BUF} 

Atomic 

blocking 

nbyte 

Atomic 

blocking 

nbyte 

Atomic 

immediate 

nbyte 

nbyte  > 
{PIPE_BUF} 

Blocking 

nbyte 

Blocking 

nbyte 

Blocking 

nbyte 

If  the  0_NONBLOCK  flag  is  clear,  a  write  request  shall  block  if  the  amount  writ¬ 
able  immediately  is  less  than  that  requested.  If  the  flag  is  set  [by  fcntli)},  a  write 
request  shall  never  block. 
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Write  to  a  Pipe  or  FIFO  with  0 NONBLOCK  set 

Immediately 

Writable: 

None 

Some 

nbyte 

nbyte  < 

{PIPE BUF} 

-1, 

[EAGAIN] 

-1, 

[EAGAIN] 

Atomic 

nbyte 

nbyte  > 
{PIPE_BUF} 

-1, 

[EAGAIN] 

<  nbyte 
or  -1, 
[EAGAIN] 

<  nbyte 
or  -1, 
[EAGAIN] 

There  is  no  exception  regarding  partial  writes  when  0_N0NBL0CK  is  set.  With  | 
the  exception  of  writing  to  an  empty  pipe,  POSIX.l  does  not  specify  exactly  when  a 
partial  write  will  be  performed  since  that  would  require  specifying  internal 
details  of  the  implementation.  Every  application  should  be  prepared  to  handle 
partial  writes  when  0_NONBLOCK  is  set  and  the  requested  amount  is  greater 
than  {PIPE_BUF},  just  as  every  application  should  be  prepared  to  handle  partial 
writes  on  other  kinds  of  file  descriptors. 

The  intent  of  forcing  writing  at  least  one  byte  if  any  can  be  written  is  to  assure  | 
that  each  write  will  make  progress  if  there  is  any  room  in  the  pipe.  If  the  pipe  is  | 
empty,  {PIPE_BUF}  bytes  must  be  written;  if  not,  at  least  some  progress  must  | 
have  been  made. 

Where  POSIX.l  requires  -1  to  be  returned  and  errno  set  to  [EAGAIN],  most  histori¬ 
cal  implementations  return  zero  (with  the  0_NDELAY  flag  set — that  flag  is  the 
historical  predecessor  of  0_NONBLOCK,  but  is  not  itself  in  POSIX.l).  The  error 
indications  in  POSIX.1  were  chosen  so  that  an  application  can  distinguish  these 
cases  from  end-of-file.  While  write ()  cannot  receive  an  indication  of  end-of-file, 
read ()  can,  and  the  two  functions  have  similar  return  values.  Also,  some  existing  | 
systems  (e.g.,  Eighth  Edition)  permit  a  write  of  zero  bytes  to  mean  that  the  reader 
should  get  an  end-of-file  indication;  for  those  systems,  a  return  value  of  zero  from 
write  ()  indicates  a  successful  write  of  an  end-of-file  indication. 

The  concept  of  a  {PIPE_MAX}  limit  (indicating  the  maximum  number  of  bytes  that 
can  be  written  to  a  pipe  in  a  single  operation)  was  considered,  but  rejected,  | 
because  this  concept  would  unnecessarily  limit  application  writing.  | 

See  also  the  discussion  of  0_NONBLOCKin  B.6. 

Writes  can  be  serialized  with  respect  to  other  reads  and  writes.  If  a  read ()  of  file  1 
data  can  be  proven  (by  any  means)  to  occur  after  a  write ()  of  the  data,  it  must  | 
reflect  that  writei) ,  even  if  the  calls  are  made  by  different  processes.  A  similar  | 
requirement  applies  to  multiple  write  operations  to  the  same  file  position.  This  is 
needed  to  guarantee  the  propagation  of  data  from  write  ()  calls  to  subsequent 
readi)  calls.  This  requirement  is  particularly  significant  for  networked  file  sys¬ 
tems,  where  some  caching  schemes  violate  these  semantics.  I 

Note  that  this  is  specified  in  terms  of  readi)  and  writei).  Additional  calls  such  as  | 
the  common  readvi)  and  writevi)  would  want  to  obey  these  semantics.  A  new 
“high-performance”  write  analog  that  did  not  follow  these  serialization  require¬ 
ments  would  also  be  permitted  by  this  wording.  POSIX.l  is  also  silent  about  any 
effects  of  application-level  caching  (such  as  that  done  by  stdio).  I 
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POSIX.  1  does  not  specify  the  value  of  the  file  offset  after  an  error  is  returned; 
there  are  too  many  cases.  For  programming  errors,  such  as  [EBADF],  the  concept 
is  meaningless  since  no  file  is  involved.  For  errors  that  are  detected  immediately, 
such  as  [EAGAIN],  clearly  the  pointer  should  not  change.  After  an  interrupt  or 
hardware  error,  however,  an  updated  value  would  be  very  useful  and  is  the 
behavior  of  many  implementations. 

POSIX.  1  does  not  specify  behavior  of  concurrent  writes  to  a  file  from  multiple 
processes.  Applications  should  use  some  form  of  concurrency  control. 


B.6.5  Control  Operations  on  Files 

B.6.5.1  Data  Definitions  for  File  Control  Operations 

The  main  distinction  between  the  file  descriptor  flags  and  the  file  status  flags  is 
scope.  The  former  apply  to  a  single  file  descriptor  only,  while  the  latter  apply  to 
all  file  descriptors  that  share  a  common  open  file  description  [by  inheritance 
through  fork ()  or  an  F_DUPFD  operation  with  fcntl()].  For  0_NONBLOCK,  this 
scoping  is  like  that  of  0_NDELAY  in  System  V  rather  than  in  4.3BSD,  where  the 
scoping  for  0_NDELAY  is  different  from  all  the  other  flags  accessed  via  the  same 
commands. 

For  example: 

fdl  =  open  (pathname,  oflags) ; 

fd2  =  dup  (fdl) ; 

fd3  =  open  (pathname,  oflags) ; 

Does  an  fcntl{)  call  on  fdl  also  apply  to  fd2  or  fd3  or  to  both?  According  to 
POSIX.l,  F_SETFD  applies  only  to  fdl,  while  F_SETFL  applies  to  fdl  and  fd2  but 
not  to  fd3.  This  is  in  agreement  with  all  common  historical  implementations 
except  for  BSD  with  the  F_SETFL  command  and  the  0_NDELAY  flag  (which  would 
apply  to  fd3  as  well).  Note  that  this  does  not  force  any  incompatibilities  in  BSD 
implementations,  because  0_NDELAY  is  not  in  POSIX.l.  See  also  B.6. 

Historically,  the  file  descriptor  flags  have  had  only  the  literal  values  0  and  1. 
POSIX.  1  defines  the  symbolic  name  FD_CLOEXEC  to  permit  a  more  graceful  exten¬ 
sion  of  this  functionality.  Owners  of  existing  applications  should  be  aware  of  the 
need  to  change  applications  using  the  literal  values,  and  implementors  should  be 
aware  of  the  existence  of  this  practice  in  existing  applications. 

B.6.5.2  File  Control 

The  ellipsis  in  the  Synopsis  is  the  syntax  specified  by  the  C  Standard  {2}  for  a 
variable  number  of  arguments.  It  is  used  because  System  V  uses  pointers  for  the 
implementation  of  file  locking  functions. 

The  arg  values  to  F_GETFD,  F_SETFD,  F_GETFL,  and  F_SETFL  all  represent  flag 
values  to  allow  for  future  growth.  Applications  using  these  functions  should  do  a 
read-modify-write  operation  on  them,  rather  than  assuming  that  only  the  values 
defined  by  POSIX.l  are  valid.  It  is  a  common  error  to  forget  this,  particularly  in 
the  case  of  F_SETFD,  because  there  is  only  one  flag  in  POSIX.l. 
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POSIX.1  permits  concurrent  read  and  write  access  to  file  data  using  the  fcntl() 
function;  this  is  a  change  from  the  1984  /usr/ group  Standard  {B59}  and  early 
POSIX.1  drafts,  which  included  a  lockfO  function.  Without  concurrency  controls, 
this  feature  may  not  be  fully  utilized  without  occasional  loss  of  data.  Since  other 
mechanisms  for  creating  critical  regions,  such  as  semaphores,  are  not  included,  a 
file  record  locking  mechanism  was  thought  to  be  appropriate.  The  fcntlO  mechan¬ 
ism  may  be  used  to  implement  semaphores,  although  access  is  not  first-in-first- 
out  without  extra  application  development  effort. 

Data  losses  occur  in  several  ways.  One  is  that  read  and  write  operations  are  not 
atomic,  and  as  such  a  reader  may  get  segments  of  new  and  old  data  if  con¬ 
currently  written  by  another  process.  Another  occurs  when  several  processes  try 
to  update  the  same  record,  without  sequencing  controls;  several  updates  may 
occur  in  parallel  and  the  last  writer  will  “win.”  Another  case  is  a  b-tree  or  other 
internal  list-based  database  that  is  undergoing  reorganization.  Without  exclusive 
use  to  the  tree  segment  by  the  updating  process,  other  reading  processes  chance 
getting  lost  in  the  database  when  the  index  blocks  are  split,  condensed,  inserted, 
or  deleted.  While  fcntl{ )  is  useful  for  many  applications,  it  is  not  intended  to  be 
overly  general  and  will  not  handle  the  b-tree  example  well. 

This  facility  is  only  required  for  regular  files  because  it  is  not  appropriate  for 
many  devices  such  as  terminals  and  network  connections. 

Since  fcntlO  works  with  “any  file  descriptor  associated  with  that  file,  however  it  is 
obtained,”  the  file  descriptor  may  have  been  inherited  through  a  forkO  or  exec 
operation  and  thus  may  affect  a  file  that  another  process  also  has  open. 

The  use  of  the  open  file  description  to  identify  what  to  lock  requires  extra  calls 
and  presents  problems  if  several  processes  are  sharing  an  open  file  description, 
but  there  are  too  many  implementations  of  the  existing  mechanism  for  POSIX.1  to 
use  different  specifications. 

Another  consequence  of  this  model  is  that  closing  any  file  descriptor  for  a  given  | 
file  (whether  or  not  it  is  the  same  open  file  description  that  created  the  lock)  | 
causes  the  locks  on  that  file  to  be  relinquished  for  that  process.  Equivalently,  any  | 
close  for  any  file/process  pair  relinquishes  the  locks  owned  on  that  file  for  that  | 
process.  But  note  that  while  an  open  file  description  may  be  shared  through 
fork (),  locks  are  not  inherited  through  fork().  Yet  locks  may  be  inherited  through 
one  of  the  exec  functions. 

The  identification  of  a  machine  in  a  network  environment  is  outside  of  the  scope 
of  POSIX.1.  Thus,  an  l_sysid  member,  such  as  found  in  System  V,  is  not  included 
in  the  locking  structure. 

Since  locking  is  performed  with  fcntl(),  rather  than  lockfO,  this  specification 
prohibits  use  of  advisory  exclusive  locking  on  a  file  that  is  not  open  for  writing. 

Before  successful  return  from  a  F_SETLK  or  F_SETLKW  request,  the  previous  lock 
type  for  each  byte  in  the  specified  region  shall  be  replaced  by  the  new  lock  type. 
This  can  result  in  a  previously  locked  region  being  split  into  smaller  regions.  If 
this  would  cause  the  number  of  regions  being  held  by  all  processes  in  the  system 
to  exceed  a  system-imposed  limit,  the  fcntl( )  function  returns  -1  with  errno  set  to 
[ENOLCK]. 
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Mandatory  locking  was  a  major  feature  of  the  1984  /usr/ group  Standard  {B59}. 
For  advisory  file  record  locking  to  be  effective,  all  processes  that  have  access  to  a 
file  must  cooperate  and  use  the  advisory  mechanism  before  doing  I/O  on  the  file. 
Enforcement-mode  record  locking  is  important  when  it  cannot  be  assumed  that  all 
processes  are  cooperating.  For  example,  if  one  user  uses  an  editor  to  update  a  file 
at  the  same  time  that  a  second  user  executes  another  process  that  updates  the 
same  file  and  if  only  one  of  the  two  processes  is  using  advisory  locking,  the 
processes  are  not  cooperating.  Enforcement-mode  record  locking  would  protect 
against  accidental  collisions. 

Secondly,  advisory  record  locking  requires  a  process  using  locking  to  bracket  each 
I/O  operation  with  lock  (or  test)  and  unlock  operations.  With  enforcement-mode 
file  and  record  locking,  a  process  can  lock  the  file  once  and  unlock  when  all  I/O 
operations  have  been  completed.  Enforcement-mode  record  locking  provides  a 
base  that  can  be  enhanced,  for  example,  with  sharable  locks.  That  is,  the 
mechanism  could  be  enhanced  to  allow  a  process  to  lock  a  file  so  other  processes 
could  read  it,  but  none  of  them  could  write  it. 

Mandatory  locks  were  omitted  for  several  reasons: 

(1)  Mandatory  lock  setting  was  done  by  multiplexing  the  set-group-ID  bit  in 
most  implementations;  this  was  confusing,  at  best. 

(2)  The  relationship  to  file  truncation  as  supported  in  4.2BSD  was  not  well 
specified. 

(3)  Any  publicly  readable  file  could  be  locked  by  anyone.  Many  historical 
implementations  keep  the  password  database  in  a  publicly  readable  file. 
A  malicious  user  could  thus  prohibit  logins.  Another  possibility  would  be 
to  hold  open  a  long-distance  telephone  line. 

(4)  Some  demand-paged  historical  implementations  offer  memory  mapped 
files,  and  enforcement  cannot  be  done  on  that  type  of  file. 

Since  sleeping  on  a  region  is  interrupted  with  any  signal,  alarm{)  may  be  used  to 
provide  a  timeout  facility  in  applications  requiring  it.  This  is  useful  in  deadlock 
detection.  Because  implementation  of  full  deadlock  detection  is  not  always  feasi¬ 
ble,  the  [EDEADLK]  error  was  made  optional. 


3699  B.6.5.3  Reposition  Read/Write  File  Offset 

3700  The  C  Standard  {2}  includes  the  functions  fgetposi)  and  fsetposO,  which  work  on 

3701  very  large  files  by  use  of  a  special  positioning  type. 

3702  Although  Iseek  ()  may  position  the  file  offset  beyond  the  end  of  the  file,  this  func- 

3703  tion  does  not  itself  extend  the  size  of  the  file.  While  the  only  function  in  POSIX.1 

3704  that  may  extend  the  size  of  the  file  is  write{),  several  C  Standard  {2}  functions, 

3705  such  as  fwriteO,  fprintfi),  etc.,  may  do  so  [by  causing  calls  on  write ()]• 

3706  An  invalid  file  offset  that  would  cause  [EINVAL]  to  be  returned  may  be  both 

3707  implementation  defined  and  device  dependent  (for  example,  memory  may  have 

3708  few  invalid  values).  A  negative  file  offset  may  be  valid  for  some  devices  in  some 

3709  implementations. 
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See  B.6.5.2  for  a  explanation  of  the  use  of  signed  and  unsigned  offsets  with 
Iseek  (). 


B.7  Device-  and  Class-Specific  Functions 

There  were  several  sources  of  difficulties  involved  with  using  historical  interfaces 
as  the  basis  of  this  section: 

(1)  The  basic  Version  7  ioctl ()  mechanism  is  difficult  to  specify  adequately, 
due  to  its  use  of  a  third  argument  that  varies  in  both  size  and  type 
according  to  the  second,  command,  argument. 

(2)  System  III  introduced  and  System  V  continued  ioctli)  commands  that  are 
completely  different  from  those  of  Version  7. 

(3)  4.2BSD  and  other  BSD  systems  added  to  the  basic  Version  7  ioctli)  com-  | 
mand  set;  some  of  these  were  for  features  such  as  job  control  that 
POSIX.1  eventually  adopted. 

(4)  None  of  the  basic  historical  implementations  are  adequate  in  an  interna¬ 
tional  environment.  This  concern  is  not  technically  within  the  scope  of 
POSIX.1,  but  the  goal  of  POSIX.1  was  to  mandate  no  unnecessary  impedi-  | 
ments  to  internationalization. 

The  1984  /usr/ group  Standard  {B59}  attempted  to  specify  a  portable  mechanism 
that  application  writers  could  use  to  get  and  set  the  modes  of  an  asynchronous 
terminal.  The  intention  of  that  committee  was  to  provide  an  interface  that  was 
neither  implementation  specific  nor  hardware  dependent.  Initial  proposals  dealt 
with  high-level  routines  similar  to  the  curses  library  (available  on  most  historical 
implementations).  In  such  an  implementation,  the  user  interface  would  consist  of 
calls  similar  to: 

set raw ( ) ; 
setcooked ( ) ; 

It  was  quickly  pointed  out  that  if  such  routines  were  standardized,  the  definition 
of  “raw”  and  “cooked”  would  have  to  be  provided.  If  these  modes  were  not  well 
defined  in  POSIX.1,  application  code  could  not  be  written  in  a  portable  way.  How¬ 
ever,  the  definition  of  the  terms  would  force  low-level  concepts  to  be  included  in  a 
supposedly  high-level  interface  definition. 

Focus  was  given  to  the  necessary  low-level  attributes  that  were  needed  to  support  | 
the  necessary  terminal  characteristics  (e.g.,  line  speeds,  raw  mode,  cooked  mode, 
etc.).  After  considerable  debate,  a  structure  similar  to,  but  more  flexible  than,  the  | 
System  III  termio  was  accepted.  The  format  of  that  structure,  referred  to  as  the  | 
termios  structure,  has  formed  the  basis  for  the  current  section. 

A  method  was  needed  to  communicate  with  the  system  about  the  termios  informa¬ 
tion.  Proposals  included: 

(1)  The  ioctli)  function  as  in  System  V.  This  had  the  same  problems  as  men¬ 
tioned  previously  for  the  Version  7  ioctli)  function  and  was  basically 
identical  to  it.  Another  problem  was  that  the  direction  of  the  command 
(whether  information  is  written  from  or  read  into  the  third  argument) 
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was  not  specified — in  historical  implementations,  only  the  device  driver 
knows  this  information.  This  was  a  problem  for  networked  implementa¬ 
tions.  It  was  also  a  problem  that  there  was  no  size  parameter  to  specify 
the  variable  size  of  the  third  argument,  and  there  was  a  similar  problem 
with  its  type. 

(2)  An  iocntl ()  function  with  additional  arguments  specifying  direction,  type, 
and  size.  But  these  new  arguments  did  not  help  application  writers,  who 
would  have  no  control  over  their  values,  which  would  have  to  match  each 
command  exactly.  The  new  arguments  did,  however,  solve  the  problems 
of  networked  implementations.  And  iocntl ()  would  have  been  implement- 
able  in  terms  of  ioctl ()  on  historical  implementations  (without  need  for 
modifying  existing  code),  although  it  would  have  been  easy  to  update 
existing  code  to  use  the  arguments  directly. 

(3)  A  termcntli)  function  with  the  same  arguments  as  proposed  for  the 
iocntl ()  function.  The  difference  was  that  termcntli)  would  be  limited  to 
terminal  interface  functions;  there  would  be  other  interface  functions, 
such  as  a  tapecntlO  function  for  tape  interfaces,  rather  than  a  single  gen¬ 
eral  device  interface  routine. 

(4)  Unspecified  functions.  The  issue  of  what  the  interface  function(s)  should 
be  called  was  avoided  for  many  of  the  early  drafts  while  details  of  the  1 
information  to  be  handled  was  of  prime  concern.  The  resulting  | 
specification  resembled  the  information  in  System  V,  but  attempted  to 
avoid  problems  of  case,  speed,  networks,  and  internationalization. 

Specific  tc*()  functions3)  to  replace  each  ioctl( )  function  were  finally  incorporated 

into  POSIX.1,  instead  of  any  of  the  previously  mentioned  proposals. 

The  issue  of  modem  control  was  excluded  from  POSIX.1  on  the  grounds  that 

—  It  was  concerned  with  setting  and  control  of  hardware  timers. 

—  The  appropriate  timers  and  settings  vary  widely  internationally. 

—  Feedback  from  European  computer  manufacturers  indicated  that  this  | 
facility  was  not  consistent  with  European  needs  and  that  specification  of  | 
such  a  facility  was  not  a  requirement  for  portability. 


B.7.1  General  Terminal  Interface 

If  the  implementation  does  not  support  this  interface  on  any  device  types,  it 
should  behave  as  if  it  were  being  used  on  a  device  that  is  not  a  terminal  device  (in 
most  cases  errno  will  be  set  to  [ENOTTY])  on  return  from  functions  defined  by  this 
interface.  This  is  based  on  the  fact  that  many  applications  are  written  to  run 
both  interactively  and  in  some  noninteractive  mode,  and  they  adapt  themselves  at 
run  time.  Requiring  that  they  all  be  modified  to  test  an  environment  variable  to 


3)  The  notation  tc*( )  is  reminiscent  of  shell  pattern  matching  notation  and  is  an  abbreviated  way  of 
referring  to  all  functions  beginning  with  the  letters  “tc.” 
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3792  determine  if  they  should  try  to  adapt  is  unnecessary.  On  a  system  that  provides 

3793  no  Section  7  interface,  providing  all  the  entry  points  as  stubs  that  return 

3794  [ENOTTY]  (or  an  equivalent,  as  appropriate)  has  the  same  effect  and  requires  no 

3795  changes  to  the  application. 

3796  Although  the  needs  of  both  interface  implementors  and  application  developers 

3797  were  addressed  throughout  POSIX.l,  this  section  pays  more  attention  to  the  needs 

3798  of  the  latter.  This  is  because,  while  many  aspects  of  the  programming  interface 

3799  can  be  hidden  from  the  user  by  the  application  developer,  the  terminal  interface  is 

3800  usually  a  large  part  of  the  user  interface.  Although  to  some  extent  the  application 

3801  developer  can  build  missing  features  or  work  around  inappropriate  ones,  the 

3802  difficulties  of  doing  that  are  greater  in  the  terminal  interface  than  elsewhere.  For 

3803  example,  efficiency  prohibits  the  average  program  from  interpreting  every  charac- 

3804  ter  passing  through  it  in  order  to  simulate  character  erase,  line  kill,  etc.  These 

3805  functions  should  usually  be  done  by  the  operating  system,  possibly  at  the  inter- 

3806  rupt  level. 

3807  The  tc*( )  functions  were  introduced  as  a  way  of  avoiding  the  problems  inherent  in 

3808  the  traditional  ioctl()  function  and  in  variants  of  it  that  were  proposed.  For  exam- 

3809  pie,  tcsetattr ()  is  specified  in  place  of  the  use  of  the  TCSETA  ioctl ()  command  func- 

3810  tion.  This  allows  specification  of  all  the  arguments  in  a  manner  consistent  with 

38U  the  C  Standard  {2},  unlike  the  varying  third  argument  of  ioctl(),  which  is  some- 

3812  times  a  pointer  (to  any  of  many  different  types)  and  sometimes  an  int. 

3813  The  advantages  of  this  new  method  include: 

3814  —  It  allows  strict  type  checking. 

3815  —  The  direction  of  transfer  of  control  data  is  explicit. 

3816  —  Portable  capabilities  are  clearly  identified. 

3817  —  The  need  for  a  general  interface  routine  is  avoided. 

3818  —  Size  of  the  argument  is  well-defined  (there  is  only  one  type). 

3819  The  disadvantages  include: 

3820  —  No  historical  implementation  uses  the  new  method. 

3821  —  There  are  many  small  routines  instead  of  one  general-purpose  one. 

3822  —  The  historical  parallel  with  fcntl{)  is  broken. 

3823  B. 7.1.1  Interface  Characteristics 

3824  B.7.1.1.1  Opening  a  Terminal  Device  File 

3825  Further  implications  of  the  effects  of  CLOCAL  are  discussed  in  7.1. 2. 4. 

3826  B.7.1.1.2  Process  Groups 

3827  There  is  a  potential  race  when  the  members  of  the  foreground  process  group  on  a 

3828  terminal  leave  that  process  group,  either  by  exit  or  by  changing  process  groups. 

3829  After  the  last  process  exits  the  process  group,  but  before  the  foreground  process 

3830  group  ID  of  the  terminal  is  changed  (usually  by  a  job-control  shell),  it  would  be 

3831  possible  for  a  new  process  to  be  created  with  its  process  ID  equal  to  the  terminal’s 
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foreground  process  group  ID.  That  process  might  then  become  the  process  group 
leader  and  accidentally  be  placed  into  the  foreground  on  a  terminal  that  was  not 
necessarily  its  controlling  terminal.  As  a  result  of  this  problem,  the  controlling 
terminal  is  defined  to  not  have  a  foreground  process  group  during  this  time. 

The  cases  where  a  controlling  terminal  has  no  foreground  process  group  occur 
when  all  processes  in  the  foreground  process  group  either  terminate  and  are 
waited  for  or  join  other  process  groups  via  setpgidi )  or  setsidi ).  If  the  process 
group  leader  terminates,  this  is  the  first  case  described;  if  it  leaves  the  process 
group  via  setpgidi),  this  is  the  second  case  described  [a  process  group  leader  can¬ 
not  successfully  call  setsidi)].  When  one  of  those  cases  causes  a  controlling  termi¬ 
nal  to  have  no  foreground  process  group,  it  has  two  visible  effects  on  applications. 
The  first  is  the  value  returned  by  tcgetpgrpi),  as  discussed  in  7.2.3  and  B.7.2.3. 
The  second  (which  occurs  only  in  the  case  where  the  process  group  leader  ter¬ 
minates)  is  the  sending  of  signals  in  response  to  special  input  characters.  The 
intent  of  POSIX.1  is  that  no  process  group  be  wrongly  identified  as  the  foreground 
process  group  by  tcgetpgrpi )  or  unintentionally  receive  signals  because  of  place¬ 
ment  into  the  foreground. 

In  4.3BSD,  the  old  process  group  ID  continues  to  be  used  to  identify  the  fore¬ 
ground  process  group  and  is  returned  by  the  function  equivalent  to  tcgetpgrpi). 
In  that  implementation  it  is  possible  for  a  newly  created  process  to  be  assigned 
the  same  value  as  a  process  ID  and  then  form  a  new  process  group  with  the  same 
value  as  a  process  group  ID.  The  result  is  that  the  new  process  group  would 
receive  signals  from  this  terminal  for  no  apparent  reason,  and  POSIX.1  precludes 
this  by  forbidding  a  process  group  from  entering  the  foreground  in  this  way.  It 
would  be  more  direct  to  place  part  of  the  requirement  made  by  the  last  sentence 
under  3.1.1,  but  there  is  no  convenient  way  for  that  subclause  to  refer  to  the  value 
that  tcgetpgrpi)  returns,  since  in  this  case  there  is  no  process  group  and  thus  no 
process  group  ID. 

One  possibility  for  a  conforming  implementation  is  to  behave  similarly  to  4.3BSD, 
but  to  prevent  this  reuse  of  the  ID,  probably  in  the  implementation  of  forki),  as 
long  as  it  is  in  use  by  the  terminal. 

Another  possibility  is  to  recognize  when  the  last  process  stops  using  the 
terminal’s  foreground  process  group  ID,  which  is  when  the  process  group  lifetime 
ends,  and  to  change  the  terminal’s  foreground  process  group  ID  to  a  reserved 
value  that  is  never  used  as  a  process  ID  or  process  group  ID.  (See  the  definition  of 
process  group  lifetime  in  2.2.2.)  The  process  ID  can  then  be  reserved  until  the  ter¬ 
minal  has  another  foreground  process  group. 

The  4.3BSD  implementation  permits  the  leader  (and  only  member)  of  the  fore¬ 
ground  process  group  to  leave  the  process  group  by  calling  the  equivalent  of 
setpgidi)  and  to  later  return,  expecting  to  return  to  the  foreground.  There  are  no 
known  application  needs  for  this  behavior,  and  POSIX.1  neither  requires  nor  for¬ 
bids  it  (except  that  it  is  forbidden  for  session  leaders)  by  leaving  it  unspecified. 

B. 7.1. 1.3  The  Controlling  Terminal 

POSIX.1  does  not  specify  a  mechanism  by  which  to  allocate  a  controlling  terminal. 
This  is  normally  done  by  a  system  utility  (such  as  getty)  and  is  considered  an 
administrative  feature  outside  the  scope  of  POSIX.1. 
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Historical  implementations  allocate  controlling  terminals  on  certain  open()  calls. 
Since  open  ()  is  part  of  POSIX.l,  its  behavior  had  to  be  dealt  with.  The  traditional  | 
behavior  is  not  required  because  it  is  not  very  straightforward  or  flexible  for 
either  implementations  or  applications.  However,  because  of  its  prevalence,  it 
was  not  practical  to  disallow  this  behavior  either.  Thus,  a  mechanism  was  stand¬ 
ardized  to  ensure  portable,  predictable  behavior  in  open(). 

Some  historical  implementations  deallocate  a  controlling  terminal  on  its  last  sys-  | 
temwide  close.  This  behavior  in  neither  required  nor  prohibited.  Even  on  imple¬ 
mentations  that  do  provide  this  behavior,  applications  generally  cannot  depend  on  j 
it  due  to  its  systemwide  nature. 

B.7.1.1.4  Terminal  Access  Control 

The  access  controls  described  in  this  subclause  apply  only  to  a  process  that  is  | 
accessing  its  controlling  terminal.  A  process  accessing  a  terminal  that  is  not  its 
controlling  terminal  is  effectively  treated  the  same  as  a  member  of  the  foreground 
process  group.  While  this  may  seem  unintuitive,  note  that  these  controls  are  for 
the  purpose  of  job  control,  not  security,  and  job  control  relates  only  to  a  process’s 
controlling  terminal.  Normal  file  access  permissions  handle  security. 

If  the  process  calling  read ()  or  write()  is  in  a  background  process  group  that  is 
orphaned,  it  is  not  desirable  to  stop  the  process  group,  as  it  is  no  longer  under  the 
control  of  a  job-control  shell  that  could  put  it  into  foreground  again.  Accordingly, 
calls  to  read()  or  write()  functions  by  such  processes  receive  an  immediate  error 
return.  This  is  different  than  in  4.2BSD,  which  kills  orphaned  processes  that 
receive  terminal  stop  signals. 

The  foreground/background/orphaned  process  group  check  performed  by  the  ter¬ 
minal  driver  must  be  repeatedly  performed  until  the  calling  process  moves  into 
the  foreground  or  until  the  process  group  of  the  calling  process  becomes  orphaned. 
That  is,  when  the  terminal  driver  determines  that  the  calling  process  is  in  the 
background  and  should  receive  a  job-control  signal,  it  sends  the  appropriate  sig¬ 
nal  (SIGTTIN  or  SIGTTOU)  to  every  process  in  the  process  group  of  the  calling  pro¬ 
cess  and  then  it  allows  the  calling  process  to  immediately  receive  the  signal.  The 
latter  is  typically  performed  by  blocking  the  process  so  that  the  signal  is  immedi¬ 
ately  noticed.  Note,  however,  that  after  the  process  finishes  receiving  the  signal 
and  control  is  returned  to  the  driver,  the  terminal  driver  must  reexecute  the  fore¬ 
ground/background/orphaned  process  group  check.  The  process  may  still  be  in 
the  background,  either  because  it  was  continued  in  the  background  by  a  job- 
control  shell,  or  because  it  caught  the  signal  and  did  nothing. 

The  terminal  driver  repeatedly  performs  the  foreground/background/orphaned 
process  group  checks  whenever  a  process  is  about  to  access  the  terminal.  In  the 
case  of  write ()  or  the  control  functions  in  7.2,  the  check  is  performed  at  the  entry 
of  the  function.  In  the  case  of  read(),  the  check  is  performed  not  only  at  the  entry 
of  the  function,  but  also  after  blocking  the  process  to  wait  for  input  characters  (if 
necessary).  That  is,  once  the  driver  has  determined  that  the  process  calling  the 
read()  function  is  in  the  foreground,  it  attempts  to  retrieve  characters  from  the 
input  queue.  If  the  queue  is  empty,  it  blocks  the  process  waiting  for  characters. 
When  characters  are  available  and  control  is  returned  to  the  driver,  the  terminal 
driver  must  return  to  the  repeated  foreground/background/orphaned  process 
group  check  again.  The  process  may  have  moved  from  the  foreground  to  the 


B.7  Device-  and  Class-Specific  Functions 


277 


3925 

3926 

3927 

3928 

3929 

3930 

3931 

3932 

3933 

3934 

3935 

3936 

3937 

3938 

3939 

3940 

3941 

3942 

3943 

3944 

3945 

3946 

3947 

3948 

3949 

3950 

3951 

3952 

3953 

3954 

3955 

3956 

3957 

3958 

3959 

3960 

3961 

3962 

3963 

3964 

3965 


ISO/IEC  9945-1:  1990 

IEEE  Std  1003.1-1990  INFORMATION  TECHNOLOGY— POSIX 

background  while  it  was  blocked  waiting  for  input  characters. 

B.7.1.1.5  Input  Processing  and  Reading  Data 
There  is  no  additional  rationale  provided  for  this  subclause. 

B.7.1.1.6  Canonical  Mode  Input  Processing 

The  term  “character”  is  intended  here.  ERASE  should  erase  the  last  character, 
not  the  last  byte.  In  the  case  of  multibyte  characters,  these  two  may  be  different. 

4.3BSD  has  a  WERASE  character  that  erases  the  last  “word”  typed  (but  not  any 
preceding  blanks  or  tabs).  A  word  is  defined  as  a  sequence  of  nonblank  charac¬ 
ters,  with  tabs  counted  as  blanks.  Like  ERASE,  WERASE  does  not  erase  beyond 
the  beginning  of  the  line.  This  WERASE  feature  has  not  been  specified  in  POSIX.  1 
because  it  is  difficult  to  define  in  the  international  environment.  It  is  only  useful 
for  languages  where  words  are  delimited  by  blanks.  In  some  ideographic 
languages,  such  as  Japanese  and  Chinese,  words  are  not  delimited  at  all.  The 
WERASE  character  should  presumably  take  one  back  to  the  beginning  of  a  sen¬ 
tence  in  those  cases;  practically,  this  means  it  would  not  get  much  use  for  those 
languages. 

It  should  be  noted  that  there  is  a  possible  inherent  deadlock  if  the  application  and  | 
implementation  conflict  on  the  value  of  MAX_CANON.  With  ICANON  set  (if  IXOFF 
is  enabled)  and  more  than  MAX_CANON  characters  transmitted  without  a  | 
linefeed,  transmission  will  be  stopped,  the  linefeed  (or  carriage  return  when  | 
ICRLF  is  set)  will  never  arrive,  and  the  read{ )  will  never  be  satisfied.  | 

An  application  should  not  set  IXOFF  if  it  is  using  canonical  mode  unless  it  knows  | 
that  (even  in  the  face  of  a  transmission  error)  the  conditions  described  previously 
cannot  be  met  or  unless  it  is  prepared  to  deal  with  the  possible  deadlock  in  some  | 
other  way,  such  as  timeouts. 

It  should  also  be  noted  that  this  can  be  made  to  happen  in  noncanonical  mode  if  | 
the  trigger  value  for  sending  IXOFF  is  less  than  VMIN  and  VTIME  is  zero. 

B.7.1.1.7  Noncanonical  Mode  Input  Processing 

Some  points  to  note  about  MIN  and  TIME: 

(1)  The  interactions  of  MIN  and  TIME  are  not  symmetric.  For  example,  when  | 
MIN  >  0  and  TIME  =  0,  TIME  has  no  effect.  However,  in  the  opposite  case 
where  MIN  =  0  and  TIME  >  0,  both  MIN  and  TIME  play  a  role  in  that  MIN 

is  satisfied  with  the  receipt  of  a  single  character. 

(2)  Also  note  that  in  case  A  (MIN  >  0,  TIME  >  0),  TIME  represents  an  inter¬ 
character  timer  while  in  case  C  (MIN  =  0,  TIME  >  0)  TIME  represents  a 
read  timer. 

These  two  points  highlight  the  dual  purpose  of  the  MIN/TIME  feature.  Cases  A 
and  B,  where  MIN  >  0,  exist  to  handle  burst-mode  activity  (e.g.,  file  transfer  pro¬ 
grams)  where  a  program  would  like  to  process  at  least  MIN  characters  at  a  time. 

In  case  A,  the  intercharacter  timer  is  activated  by  a  user  as  a  safety  measure;  in 
case  B,  it  is  turned  off. 
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3966  Cases  C  and  D  exist  to  handle  single-character  timed  transfers.  These  cases  are 

3967  readily  adaptable  to  screen-based  applications  that  need  to  know  if  a  character  is 

3968  present  in  the  input  queue  before  refreshing  the  screen.  In  case  C  the  read  is 

3969  timed;  in  case  D,  it  is  not. 

3970  Another  important  note  is  that  MIN  is  always  just  a  minimum.  It  does  not  denote 

3971  a  record  length.  That  is,  if  a  program  does  a  read  of  20  bytes,  MIN  is  10,  and  25 

3972  characters  are  present,  20  characters  shall  be  returned  to  the  user.  In  the  special  | 

3973  case  of  MIN=0,  this  still  applies:  if  more  than  one  character  is  available,  they  all  | 

3974  will  be  returned  immediately.  | 

3975  B.7.1.1.8  Writing  Data  and  Output  Processing 

3976  There  is  no  additional  rationale  provided  for  this  subclause. 

3977  B.7.1.1.9  Special  Characters 

3978  There  is  no  additional  rationale  provided  for  this  subclause. 

3979  B.7.1.1.10  Modem  Disconnect 

3980  There  is  no  additional  rationale  provided  for  this  subclause. 

3981  B.7.1.1.11  Closing  a  Terminal  Device  File 

3982  POSIX.1  is  silent  on  whether  a  closei)  will  block  on  waiting  for  transmission  to  | 

3983  drain,  or  even  if  a  closei )  might  cause  a  flush  of  pending  output.  If  the  application  | 

3984  is  concerned  about  this,  it  should  call  the  appropriate  function,  such  as  tcdraini),  \ 

3985  to  ensure  the  desired  behavior.  | 

3986  B.7.1.2  Parameters  That  Can  Be  Set  | 

3987  B.7.1.2.1  termios  Structure 

3988  This  structure  is  part  of  an  interface  that,  in  general,  retains  the  historic  group- 

3989  ing  of  flags.  Although  a  more  optimal  structure  for  implementations  may  be  pos- 

3990  sible,  the  degree  of  change  to  applications  would  be  significantly  larger. 

3991  B.7.1.2.2  Input  Modes 

3992  Some  historical  implementations  treated  a  long  break  as  multiple  events,  as 

3993  many  as  one  per  character  time.  The  wording  in  POSIX.1  explicitly  prohibits  this. 

3994  Although  the  ISTRIP  flag  is  normally  superfluous  with  today’s  terminal  hardware 

3995  and  software,  it  is  historically  supported.  Therefore,  applications  may  be  using 

3996  ISTRIP,  and  there  is  no  technical  problem  with  supporting  this  flag.  Also,  applica- 

3997  tions  may  wish  to  receive  only  7-bit  input  bytes  and  may  not  be  connected  directly 

3998  to  the  hardware  terminal  device  (for  example,  when  a  connection  traverses  a 

3999  network). 

4000  Also,  there  is  no  requirement  in  general  that  the  terminal  device  ensures  that 

4001  high-order  bits  beyond  the  specified  character  size  are  cleared.  ISTRIP  provides 

4002  this  function  for  7-bit  characters,  which  are  common. 
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4003  In  dealing  with  multibyte  characters,  the  consequences  of  a  parity  error  in  such  a 

4004  character,  or  in  an  escape  sequence  affecting  the  current  character  set,  are  beyond 

4005  the  scope  of  POSIX.1  and  are  best  dealt  with  by  the  application  processing  the 

4006  multibyte  characters. 

4007  B.7.1.2.3  Output  Modes 

4008  POSIX.1  does  not  describe  postprocessing  of  output  to  a  terminal  or  detailed  con- 

4009  trol  of  that  from  a  portable  application.  (That  is,  translation  of  newline  to  car- 

4010  riage  return  followed  by  linefeed  or  tab  processing.)  There  is  nothing  that  a  port- 

4011  able  application  should  do  to  its  output  for  a  terminal  because  that  would  require 

4012  knowledge  of  the  operation  of  the  terminal.  It  is  the  responsibility  of  the  operat- 

4013  ing  system  to  provide  postprocessing  appropriate  to  the  output  device,  whether  it 

4014  is  a  terminal  or  some  other  type  of  device. 

4015  Extensions  to  POSIX.1  to  control  the  type  of  postprocessing  already  exist  and  are 

4016  expected  to  continue  into  the  future.  The  control  of  these  features  is  primarily  to 

4017  adjust  the  interface  between  the  system  and  the  terminal  device  so  the  output 

4018  appears  on  the  display  correctly.  This  should  be  set  up  before  use  by  any 

4019  application. 

4020  In  general,  both  the  input  and  output  modes  should  not  be  set  absolutely,  but 

4021  rather  modified  from  the  inherited  state. 

4022  B.7.1.2.4  Control  Modes 

4023  This  subclause  could  be  misread  that  the  symbol  “CSIZE”  is  a  title  in  Table  7-3.  | 

4024  Although  it  does  serve  that  function,  it  is  also  a  required  symbol,  as  a  literal  read-  | 

4025  ing  of  POSIX.1  (and  the  caveats  about  typography)  would  indicate.  | 

4026  B.7.1.2.5  Local  Modes 

4027  Noncanonical  mode  is  provided  to  allow  fast  bursts  of  input  to  be  read  efficiently 

4028  while  still  allowing  single-character  input. 

4029  The  ECHONL  function  historically  has  been  in  many  implementations.  Since 

4030  there  seems  to  be  no  technical  problem  with  supporting  ECHONL,  it  is  included  in 

4031  POSIX.1  to  increase  consensus. 

4032  The  alternate  behavior  possible  when  ECHOK  or  ECHOE  are  specified  with 

4033  ICANON  is  permitted  as  a  compromise  depending  on  what  the  actual  terminal 

4034  hardware  can  do.  Erasing  characters  and  lines  is  preferred,  but  is  not  always 

4035  possible. 

4036  B.7. 1.2.6  Special  Control  Characters 

4037  Permitting  VMIN  and  VTIME  to  overlap  with  VEOF  and  VEOL  was  a  compromise 

4038  for  historical  implementations.  Only  when  backwards  compatibility  of  object  code  | 

4039  is  a  serious  concern  to  an  implementor  should  an  implementation  continue  this 

4040  practice.  Correct  applications  that  work  with  the  overlap  (at  the  source  level) 

4041  should  also  work  if  it  is  not  present,  but  not  the  reverse. 
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B.7.1.2.7  Baud  Rate  Values 

There  is  no  additional  rationale  provided  for  this  subclause. 

B.7.1.3  Baud  Rate  Functions 

The  term  baud  is  used  historically  here,  but  is  not  technically  correct.  This  is 
properly  “bits  per  second,”  which  may  not  be  the  same  as  “baud.”  However,  the 
term  is  used  because  of  the  historical  usage  and  understanding. 

These  functions  do  not  take  numbers  as  arguments,  but  rather  symbolic  names. 
There  are  two  reasons  for  this: 

—  Historically,  numbers  were  not  used  because  of  the  way  the  rate  was  stored 
in  the  data  structure.  This  is  retained  even  though  an  interface  function  is 
now  used. 

—  More  importantly,  only  a  limited  set  of  possible  rates  is  at  all  portable,  and 
this  constrains  the  application  to  that  set. 

There  is  nothing  to  prevent  an  implementation  to  accept,  as  an  extension,  a 
number  (such  as  126)  if  it  wished,  and  because  the  encoding  of  the  Bxxx  symbols 
is  not  specified,  this  can  be  done  so  no  ambiguity  is  introduced. 

Setting  the  input  baud  rate  to  zero  was  a  mechanism  to  allow  for  split  baud  rates. 
Clarifications  to  this  version  of  POSIX.1  have  made  it  possible  to  determine  if  split 
rates  are  supported  and  to  support  them  without  having  to  treat  zero  as  a  special 
case.  Since  this  functionality  is  also  confusing,  it  has  been  declared  obsolescent. 
The  0  argument  referred  to  is  the  literal  constant  0,  not  the  symbolic  constant  B0. 
POSIX.1  does  not  preclude  B0  from  being  defined  as  the  value  0;  in  fact,  imple¬ 
mentations  will  likely  benefit  from  the  two  being  equivalent.  POSIX.1  does  not 
fully  specify  whether  the  previous  cfsetispeedi  )  value  is  retained  after  a  tcgetattr () 
as  the  actual  value  or  as  zero.  Therefore,  portable  applications  should  always  set 
both  the  input  speed  and  output  speed  when  setting  either. 

In  historical  implementations,  the  baud  rate  information  is  traditionally  kept  in 
cjcflag.  Applications  should  be  written  to  presume  that  this  might  be  the  case 
(and  thus  not  blindly  copy  cjcflag)  but  not  to  rely  on  it,  in  case  it  is  in  some  other 
field  of  the  structure.  Setting  the  cjcflag  field  absolutely  after  setting  a  baud  rate 
is  a  nonportable  action  because  of  this.  In  general,  the  unused  parts  of  the  flag 
fields  might  be  used  by  the  implementation  and  should  not  be  blindly  copied  from 
the  descriptions  of  one  terminal  device  to  another. 


B.7.2  General  Terminal  Interface  Control  Functions 

The  restrictions  described  in  this  subclause  on  access  from  processes  in  back-  | 
ground  process  groups  controls  apply  only  to  a  process  that  is  accessing  its  con¬ 
trolling  terminal.  (See  B.7. 1.1.4). 

Care  must  be  taken  when  changing  the  terminal  attributes.  Applications  should 
always  do  a  tcgetattr( ),  save  the  termios  structure  values  returned,  and  then  do  a 
tcsetattr()  changing  only  the  necessary  fields.  The  application  should  use  the 
values  saved  from  the  tcgetattr( )  to  reset  the  terminal  state  whenever  it  is  done 
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4083  with  the  terminal.  This  is  necessary  because  terminal  attributes  apply  to  the 

4084  underlying  port  and  not  to  each  individual  open  instance;  that  is,  all  processes 

4085  that  have  used  the  terminal  see  the  latest  attribute  changes. 

4086  A  program  that  uses  these  functions  should  be  written  to  catch  all  signals  and 

4087  take  other  appropriate  actions  to  assure  that  when  the  program  terminates, 

4088  whether  planned  or  not,  the  terminal  device’s  state  is  restored  to  its  original 

4089  state.  See  also  B. 7.1. 

4090  Existing  practice  dealing  with  error  returns  when  only  part  of  a  request  can  be  | 

4091  honored  is  based  on  calls  to  the  ioctli)  function.  In  historical  BSD  and  System  V  | 

4092  implementations,  the  corresponding  ioctli )  returns  zero  if  the  requested  actions  | 

4093  were  semantically  correct,  even  if  some  of  the  requested  changes  could  not  be  | 

4094  made.  Many  existing  applications  assume  this  behavior  and  would  no  longer  | 

4095  work  correctly  if  the  return  value  were  changed  from  zero  to  -1  in  this  case.  | 

4096  Note  that  either  specification  has  a  problem.  When  zero  is  returned,  it  implies  | 

4097  everything  succeeded  even  if  some  of  the  changes  were  not  made.  When  -1  is  | 

4098  returned,  it  implies  everything  failed  even  though  some  of  the  changes  were  | 

4099  made.  | 

4100  Applications  that  need  all  of  the  requested  changes  made  to  work  properly  should  j 

4101  follow  tcsetattr ()  with  a  call  to  tcgetattri)  and  compare  the  appropriate  field  | 

4102  values.  | 

4103  B.7.2.1  Get  and  Set  State 

4104  The  tcsetattri )  function  can  be  interrupted  in  the  following  situations:  | 

4105  —  It  is  interrupted  while  waiting  for  output  to  drain.  | 

4106  —  It  is  called  from  a  process  in  a  background  process  group  and  SIGTTOU  is  | 

4107  caught.  | 

4108  B.7.2.2  Line  Control  Functions 

4109  There  is  no  additional  rationale  provided  for  this  subclause. 

4110  B.7.2.3  Get  Foreground  Process  Group  ID 

4iu  The  tcgetpgrp ()  function  has  identical  functionality  to  the  4.2BSD  ioctli )  function 

4112  TIOCGPGRP  except  for  the  additional  security  restriction  that  the  referenced  ter- 

4113  minal  must  be  the  controlling  terminal  for  the  calling  process. 

4114  In  the  case  where  there  is  no  foreground  process  group,  returning  an  error  rather  | 

4H5  than  a  positive  value  was  considered.  This  was  rejected  because  existing  applica-  | 

4116  tions  based  on  either  IEEE  Std  1003.1-1988  or  4.3BSD  are  likely  to  consider  errors  | 

4117  from  this  call  or  the  BSD  equivalent  to  be  catastrophic  and  respond  inappropri-  | 

4118  ately.  Such  applications  implicitly  assume  that  this  case  does  not  exist,  and  the  | 

4119  positive  return  value  is  the  only  solution  that  permits  them  to  behave  properly  | 

4120  even  when  they  do  encounter  it.  No  application  has  been  identified  that  can  | 

4121  benefit  from  distinguishing  between  this  case  and  the  case  of  a  valid  foreground  | 

4122  process  group  other  than  its  own.  Therefore,  requiring  or  permitting  any  other  | 
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4123  solution  would  cause  more  application  portability  problems  with  no  corresponding 

4124  benefit  to  applications.  The  value  must  be  positive,  not  zero,  because  applications 

4125  may  use  the  negation  as  the  pid  argument  to  kill().  In  addition,  the  value  1  must 

4126  not  be  used  so  that  an  attempt  to  send  a  signal  to  this  (nonexistent)  process  group 

4127  does  not  result  in  broadcasting  a  signal  unintentionally.  See  also  B. 7.1. 1.2. 

4128  B.7.2.4  Set  Foreground  Process  Group  ID 

4129  The  tcsetpgrpO  function  has  identical  functionality  to  the  4.2BSD  ioctl()  function 

4130  TIOCSPGRP  except  for  the  additional  security  restrictions  that  the  referenced  ter- 

4131  minal  must  be  the  controlling  terminal  for  the  calling  process  and  the  specified 

4132  new  process  group  must  be  currently  in  use  in  the  caller’s  session. 


4133  B.8  Language-Specific  Services  for  the  C  Programming  Language 

4134  See  the  discussion  of  C  functions  in  B. 1.1.1.  | 

4135  Common  usage  may  be  defined  by  historical  publications  such  as  The  C  Program-  | 

4136  ming  Language  {B46}. 

4137  The  null  set  of  supported  languages  is  allowed. 

4138  The  list  of  functions  comprises  the  list  of  “common-usage”  functions  and  also 

4139  includes  those  that  are  not  in  common  usage  that  are  addressed  by  POSIX.l.  The 

4140  rules  for  common-usage  conformance  to  POSIX.1  address  whether  the  functions 

4141  that  are  not  generally  considered  in  common  usage  are  implemented.  There  are  a 

4142  large  number  of  functions  found  in  various  systems  that,  although  frequently 

4143  found,  are  not  broadly  enough  available  to  be  considered  in  common  usage.  The 

4144  signal ()  function  (although  in  common  usage)  is  omitted  because  applications  con-  | 

4145  forming  to  POSIX.l  should  use  the  more  reliable  sigaction ()  interface  instead. 

4146  B.8.1  Referenced  C  Language  Routines 

4147  B.8.1. 1  Extensions  to  Time  Functions 

4148  System  V  uses  the  TZ  environment  variable  to  set  some  information  about  time. 

4149  It  has  the  form  (spaces  inserted  for  clarity): 

4150  std  offset  dst 

4151  where  the  first  three  characters  (std)  are  the  name  of  the  standard  time  zone,  the 

4152  digits  that  follow  ( offset )  represent  the  time  added  to  the  local  time  zone  to  arrive 

4153  at  Coordinated  Universal  Time,  and  the  next  three  characters  (dst)  are  the  name 

4154  of  the  summer  time  zone.  The  meaning  of  offset  implies  that  most  sites  west  of 

4155  the  Prime  Meridian  will  have  a  positive  offset  (preceded  by  an  optional  plus  sign, 

4156  “+”),  while  most  sites  east  of  the  Prime  Meridian  will  have  a  negative  offset  (pre- 

4157  ceded  by  a  minus  sign,  “-”).  Both  std  and  offset  are  required;  if  dst  is  missing, 

4158  summer  time  does  not  apply. 
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Currently,  the  UNIX  system  localtime ()  function  translates  a  number  of  seconds 
since  the  Epoch  into  a  detailed  breakdown  of  that  time.  This  breakdown  includes 

(1)  Time  of  day:  Hours,  minutes,  and  seconds. 

(2)  Day  of  the  month,  month  of  the  year,  and  the  year. 

(3)  Day  of  the  week  and  day  of  the  year  (Julian  day). 

(4)  Whether  or  not  summer  (daylight  saving)  time  is  in  effect. 

It  is  the  first  and  last  items  that  present  a  problem:  the  time  of  the  day  depends 
on  whether  or  not  summer  time  is  in  effect.  Whether  or  not  summer  time  is  in 
effect  depends  on  the  locale  and  date. 

Most  historical  systems  had  time-zone  rules  compiled  into  the  C  library.  These 
rules  usually  represented  United  States  rules  for  1970  to  1986.  This  did  not 
accommodate  the  changes  of  1987,  nor  other  world  variations  (V2-hour  time,  dou¬ 
ble  daylight  time,  and  solar  time  being  common,  but  not  complete,  examples). 
Some  recent  systems  addressed  these  problems  in  various  ways. 

Having  the  rules  compiled  into  the  program  made  binary  distributions  that 
accommodated  all  the  variations  (including  sudden  changes  to  the  law),  and  per- 
process  rule  changes,  difficult  at  best. 

POSIX.  1  includes  a  way  of  specifying  the  time  zone  in  the  TZ  string,  but  only  per¬ 
mits  one  time-zone  pattern  at  a  time,  thus  not  dealing  with  different  patterns  in 
previous  years  and  with  such  issues  as  solar  time.  Methods  exist  to  deal  with  all 
the  problems  above.  The  method  in  POSIX.  1  appears  to  be  simpler  to  implement 
and  may  be  faster  in  execution  when  it  is  adequate.  POSIX.  1  also  permits  an 
implementation-defined  rule  set  that  begins  with  a  colon.  (The  previous  format 
cannot  begin  with  a  colon.) 

Rules  of  the  form  AAAn  or  AAAnBBB  (the  style  used  in  many  historical  implemen¬ 
tations)  do  not  carry  with  them  any  statement  about  the  start  and  end  of  daylight 
time  (neither  the  date  nor  the  time  of  day;  the  default  to  02:00  not  applying  if  no 
rule  is  present  at  all),  thus  implying  that  the  implementation  must  provide  the 
appropriate  rules.  An  implementation  may  provide  those  rules  in  any  way  it  sees 
fit,  as  long  as  the  constraints  implied  by  the  TZ  string  as  provided  by  the  user  are 
met.  Specifically,  the  implementation  may  use  the  string  as  an  index  into  a  table, 
which  may  reside  either  on  disk  or  in  memory.  Such  tables  could  contain  rules 
that  are  sensitive  to  the  year  to  which  they  are  applied,  again  since  the  user  did 
not  specify  the  exact  rule.  (Although  impractical,  every  possible  TZ  string  could 
be  represented  in  a  table,  as  a  detail  of  implementation;  the  less  specific  the  user 
is  about  the  TZ  string,  the  more  freedom  the  implementation  has  to  interpret  it.) 

There  is  at  least  one  public-domain  time-zone  implementation  (the  Olson/Harris 
method)  that  uses  nonspecific  TZ  strings  and  a  table,  as  described  previously,  and 
handles  all  the  general  time-zone  problems  mentioned  above.  This  implementa¬ 
tion  also  appears  in  a  late  release  of  4.3BSD.  If  this  implementation  honors  all 
the  specifications  provided  in  the  TZ  string,  it  would  conform  to  POSIX.  1.  Nothing 
precludes  the  implementation  from  adding  information  beyond  that  given  by  the 
user  in  the  TZ  string. 

The  fully  specified  TZ  environment  variable  extends  the  historical  meaning  to  also 
include  a  rule  for  when  to  use  standard  time  and  when  to  use  summer  time. 
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4204  Southern  hemisphere  time  zones  are  supported  by  allowing  the  first  rule  date 

4205  (change  to  summer  time)  to  be  later  in  the  year  than  the  second  rule  date  (change 

4206  to  standard  time). 

4207  This  mechanism  accommodates  the  “floating  day”  rules  (for  example  “last  Sunday 

4208  in  October”)  used  in  the  United  States  and  Canada  (and  the  European  Economic 

4209  Community  for  the  last  several  years).  In  theory,  TZ  only  has  to  be  set  once  and 

4210  then  never  touched  again  unless  the  law  is  changed. 

42U  Julian  dates  are  proposed  with  two  syntaxes,  one  zero-based,  the  other  one-based. 

4212  They  are  here  for  historical  reasons.  The  one-based  counting  (J)  is  used  more 

4213  commonly  in  Europe  (and  on  calendars  people  may  use  for  reference).  The  zero- 

4214  based  counting  (n)  is  used  currently  in  some  implementations  and  should  be  kept 

4215  for  historical  reasons  as  well  as  being  the  only  way  to  specify  Leap  Day. 

4216  It  is  expected  that  the  leading  colon  format  will  allow  systems  to  implement  an 

4217  even  broader  range  of  specifications  for  the  time  zone  without  having  to  resort  to  a 

4218  file  or  permit  naming  an  explicit  file  containing  the  appropriate  rules. 

4219  The  specification  in  POSIX.l  for  TZ  assumes  that  very  few  programs  need  to  be 

4220  historically  accurate  as  long  as  the  relative  timing  of  two  events  is  preserved. 

4221  Summer  time  is  governed  by  both  locale  and  date.  This  proposal  only  handles  the 

4222  locale  dependency.  Using  an  implementation-defined  file  format  for  either  the 

4223  entire  TZ  variable  or  to  specify  the  rules  for  a  particular  time  zone  is  allowed  as  a 

4224  means  by  which  both  the  locale  and  date  dependency  can  be  handled. 

4225  Since  historical  implementations  do  not  examine  TZ  beyond  the  assumed  end  of 

4226  dst,  it  is  possible  literally  to  extend  TZ  and  break  very  little  existing  software. 

4227  Since  much  historical  software  does  not  function  outside  the  US  time  zones,  minor 

4228  changes  to  TZ  (such  as  extending  offset  to  be  hh  :mm — as  long  as  the  colon  and 

4229  minutes,  :mm,  are  optional)  should  have  little  effect. 

4230  POSIX.1  is  intentionally  silent  about  values  of  TZ  that  do  not  fit  either  of  the  | 

4231  specified  forms.  It  simply  requires  that  TZ  values  that  follow  those  forms  be  | 

4232  interpreted  as  specified. 

4233  B.8.1.2  Extensions  to  setlocaleO  Function 

4234  The  C  Standard  {2}  defines  a  collection  of  interfaces  to  support  intemationaliza- 

4235  tion.  One  of  the  most  significant  aspects  of  these  interfaces  is  a  facility  to  set  and 

4236  query  the  international  environment.  The  international  environment  is  a  reposi- 

4237  tory  of  information  that  affects  the  behavior  of  certain  functionality,  namely 


4238 

(1) 

Character  Handling 

4239 

(2) 

String  Handling  (i.e.,  collating) 

4240 

(3) 

Date/Time  Formatting 

4241 

(4) 

Numeric  Editing 

4242  The  setlocaleO  function  provides  the  application  developer  with  the  ability  to  set 

4243  all  or  portions,  called  categories ,  of  the  international  environment.  These 

4244  categories  correspond  to  the  areas  of  functionality,  mentioned  above.  The  syntax 

4245  for  set  locale  ( )  is  the  following: 
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char  *setlocale  (int  category,  const  char  *locale)  ; 
where  category  is  the  name  of  one  of  five  categories,  namely 

LC _ CTYPE 

LC_COLLATE 

LC_TIME 

LC_MONETARY 

LC_NUMERIC 

In  addition,  a  special  value,  called  LC_ALL,  directs  setlocale ()  to  set  all  categories. 

The  locale  argument  is  a  character  string  that  points  to  a  specific  setting  for  the 
international  environment,  or  locale.  There  are  three  preset  values  for  the  locale 
argument,  namely 

"C"  Specifies  the  minimal  environment  for  C  translation.  If  setlocalei ) 

is  not  invoked,  the  “C”  locale  is  the  default. 

"posix"  Specifies  a  locale  that  is  the  same  as  "C"  for  the  attributes  defined  | 
by  the  C  Standard  {2}  and  POSIX.  1,  but  may  contain  extensions.  | 
The  wording  permits  extensions  by  standards,  specifically  that  of  j 
ISO/IEC  9945-2  {B36},  which  is  expected  to  use  the  same  symbol,  j 
and  by  future  versions  of  POSIX.  1.  | 

"  "  Specifies  an  implementation-defined  native  environment. 

NULL  Used  to  direct  setlocale ()  to  query  the  current  international 
environment  and  return  the  name  of  the  locale. 


This  subclause  describes  the  behavior  of  an  implementation  of  setlocale  ()  and  its  | 
use  of  environment  variables  in  controlling  this  behavior  on  POSIX.  1-based  sys-  | 
terns.  There  are  two  primary  uses  of  setlocalei ): 

(1)  Querying  the  international  environment  to  find  out  what  it  is  set  to; 

(2)  Setting  the  international  environment,  or  locale,  to  a  specific  value. 

The  following  subclauses  describe  the  behavior  of  setlocalei)  in  these  two  areas.  | 
Since  it  is  difficult  to  describe  the  behavior  in  words,  examples  will  be  used  to 
illustrate  the  behavior  of  specific  uses. 


To  query  the  international  environment,  setlocalei )  is  invoked  with  a  specific 
category  and  the  NULL  pointer  as  the  locale.  The  NULL  pointer  is  a  special  direc¬ 
tive  to  setlocalei)  that  tells  it  to  query  rather  than  set  the  international  environ¬ 
ment.  The  following  syntax  is  used  to  query  the  name  of  the  international 
environment: 


setlocale  ( - 


LC_ALL 
LCjCTYPE 
LCjCOLLATE 
LCTIME 
LC  NUMERIC 
LC  MONETARY 


ichar  * )  NULL ); 


The  setlocalei)  function  returns  the  string  corresponding  to  the  current  interna¬ 
tional  environment.  This  value  may  be  used  by  a  subsequent  call  to  setlocalei)  to 
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reset  the  international  environment  to  this  value.  However,  it  should  be  noted 
that  the  return  value  from  setlocale ()  is  a  pointer  to  a  static  area  within  the  func¬ 
tion  and  is  not  guaranteed  to  remain  unchanged  [i.e.,  it  may  be  modified  by  a  sub¬ 
sequent  call  to  setlocale ()].  Therefore,  if  the  purpose  of  calling  setlocale()  is  to 
save  the  value  of  the  current  international  environment  so  it  can  be  changed  and 
reset  later,  the  return  value  should  be  copied  to  an  array  of  char  in  the  calling  | 
program.  | 

There  are  three  ways  to  set  the  international  environment  with  setlocale (): 

setlocale  {category,  string) 

This  usage  will  set  a  specific  category  in  the  international 
environment  to  a  specific  value  corresponding  to  the  value  of 
the  string.  A  specific  example  is  provided  below: 

setlocale  (LC_ALL,  "Fr_FR. 8859" )  ; 

In  this  example,  all  categories  of  the  international  environment 
will  be  set  to  the  locale  corresponding  to  the  string 
"Fr__FR.  8  8  59",  or  to  the  French  language  as  spoken  in  France 
using  the  ISO  8859-1  code  set. 

If  the  string  does  not  correspond  to  a  valid  locale,  setlocale () 
will  return  a  NULL  pointer  and  the  international  environment 
is  not  changed.  Otherwise,  setlocale ()  will  return  the  name  of 
the  locale  just  set. 

setlocale  (category,  "C") 

The  C  Standard  {2}  states  that  one  locale  must  exist  on  all  con¬ 
forming  implementations.  The  name  of  the  locale  is  "C"  and 
corresponds  to  a  minimal  international  environment  needed  to 
support  the  C  programming  language. 

setlocale  (category,  "") 

This  will  set  a  specific  category  to  an  implementation-defined 
default.  For  POSIX.l -based  systems,  this  corresponds  to  the 
value  of  the  environment  variables. 


B.8.2  C  Language  Input/Output  Functions 
B.8.2.1  Map  a  Stream  Pointer  to  a  File  Descriptor 

Without  some  specification  of  which  file  descriptors  are  associated  with  these 
streams,  it  is  impossible  for  an  application  to  set  up  the  streams  for  another  appli¬ 
cation  it  starts  with  fork()  and  exec.  In  particular,  it  would  not  be  possible  to 
write  a  portable  version  of  the  sh  command  interpreter  (although  there  may  be 
other  constraints  that  would  prevent  that  portability). 

B.8.2.2  Open  a  Stream  on  a  File  Descriptor 

The  file  descriptor  may  have  been  obtained  from  open(),  creat(),  pipe (),  dup(),  or 
fcntl() ;  inherited  through  fork{ )  or  exec;  or  perhaps  obtained  by  implementation- 
dependent  means,  such  as  the  4.3BSD  socket ()  call. 
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The  meanings  of  the  type  arguments  of  fdopenO  and  fopen ()  differ.  With  fdo- 
pen(),  open  for  write  ("w"  or  "w+")  does  not  truncate,  and  append  ("a"  or  "a+") 
cannot  create  for  writing.  There  is  no  need  for  "b"  in  the  format  due  to  the 
equivalence  of  binary  and  text  files  in  POSIX.  1.  See  B.  1.1.1.  Although  not  expli-  | 
citly  required  by  POSIX.  1,  a  good  implementation  of  append  ("a")  mode  would  | 
cause  the  0_APPEND  flag  to  be  set.  | 

B.8.2.3  Interactions  of  Other  FILE- Type  C  Functions 

Note  that  the  existence  of  open  streams  on  a  file  implies  open  file  descriptors  and 
thus  affects  the  timestamps  of  the  file.  The  intent  is  that  using  stdio  routines  to 
read  a  file  must  eventually  update  the  access  time,  and  using  them  to  write  a  file 
must  eventually  update  the  modify  and  change  times.  However,  the  exact  timing 
of  marking  the  st_atime,  stjctime,  and  stjntime  fields  cannot  be  specified,  as  that 
would  imply  a  particular  buffering  strategy. 

The  purpose  of  the  rules  about  handles  is  to  allow  the  writing  of  a  program  that 
uses  stdio  and  does  some  shell-like  things;  in  particular,  creating  an  open  file  for 
a  child  process  to  use,  where  both  the  parent  and  child  wish  to  use  stdio,  with  the 
consequences  of  buffering.  In  most  cases,  this  cannot  happen  in  the  C  Standard  | 
{2}  (because  there  is  no  way  to  create  a  second  handle),  but  the  systemO  function 
can  cause  this  to  occur,  at  least  in  most  historical  implementations. 

Presently,  POSIX.  1  deals  mostly  with  output  streams;  input  is  implementation  | 
defined.  It  should  be  possible  to  make  input  on  seekable  devices  work  for  seek-  | 
able  files  without  affecting  buffering  strategies  significantly.  However,  the  details  | 
have  not  been  worked  out  fully  and  will  be  addressed  in  a  future  revision  of  | 
POSIX.l.  The  requirements  on  applications  are  unlikely  to  change  [basically,  | 
serving  notice  to  the  implementation  that  the  use  of  a  particular  handle  is  (tern-  | 
porarily)  completed]  and  are  symmetric  to  those  for  output.  | 

There  are  some  implied  rules  about  interprocess  synchronization,  but  no  mechan¬ 
ism  is  given,  intentionally.  In  the  simplest  case,  if  the  parent  meets  the  require¬ 
ments  on  all  its  files  and  then  performs  a  forkO  and  a  wait()  before  further 
activity  on  them  [and  a  fflushO  on  input  files  after  that],  the  desired  synchroniza¬ 
tion  will  be  achieved.  Synchronization  could  in  theory  be  done  with  signals,  but 
the  only  likely  case  is  the  one  just  described.  The  terms  handle  and  active  handle 
were  required  to  make  the  text  readable  and  are  not  intended  for  use  outside  this 
discussion. 

Note  that  since  exit{)  implies  _exit(),  a  file  descriptor  is  also  closed  by  exit{). 

Because  a  handle  is  either  freshly  opened,  or  if  not  must  have  handed  off  control 
of  the  open  file  description  as  specified,  the  new  handle  is  always  ready  to  be  used 
(except  for  seeks)  with  no  initialization.  [A  freshly  opened  stream  has  not  yet 
done  any  reads,  as  required  by  the  C  Standard  [2],  at  least  implicitly  by  the  rules  | 
associated  with  setvbufi).] 

In  requiring  the  seek  to  an  appropriate  location  for  the  new  handle,  the  applica¬ 
tion  is  required  to  know  what  it  is  doing  if  it  is  passing  streams  with  seeks 
involved.  If  the  required  seek  is  not  done,  the  results  are  undefined  (and  in  fact 
the  program  probably  will  not  work  on  many  common  implementations). 
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A  naive  program  used  as  a  utility  can  be  reasonably  expected  to  work  properly 
when  the  constraints  are  met  by  the  calling  program  because  it  will  not  hand  off 
file  descriptors  except  with  closes. 

The  exec  functions  are  treated  specially  because  the  application  should  always 
fflushi)  everything  before  performing  one  of  the  exec  functions.  If  stdout  is  avail¬ 
able  on  the  same  open  file  description  after  the  exec,  it  is  a  different  stream,  at 
least  because  any  unflushed  data  will  be  discarded  during  the  exec  (similarly  for 
stdin ).  Process  termination  is  also  special  because  a  process  terminating  due  to  a 
signal  or  _exit{ )  will  not  have  the  buffers  flushed. 

The  fork ()  function  also  must  be  specially  treated  because  it  clones  a  number  of 
file  descriptors  simultaneously.  Thus,  all  of  them  should  be  prepared  for  handoff 
before  the  fork ().  In  effect,  fork()  creates  a  pair  of  handles  that  are  improperly 
dealt  with  unless,  before  the  fork(),  the  first  part  of  a  handoff  occurred.  Note  that 
fflushCNULL )  in  the  C  Standard  {2}  is  an  appropriate  way  to  do  this  for  output.  A 
subsequent  exec  call  [that  does  not  succeed  in  calling  exit()  in  some  way]  will 
reduce  the  number  of  handles  back  to  the  original  value  (allowing  for  files  that 
are  not  close-on-exec),  and,  thus,  preparations  for  exec  need  not  necessarily  do  the 
flush.  However,  because  exit{)  closes  all  streams,  if  the  exec  fails,  the  application 
must  be  careful  to  terminate  with  _exit(). 

POSIX.1  does  not  specify  asynchronous  I/O,  and  when  dealing  with  asynchronous 
I/O  the  problem  of  coordinating  access  to  streams  will  be  more  difficult.  If  asyn¬ 
chronous  I/O  is  provided  as  an  extension,  the  problems  it  introduces  in  this  area 
should  be  addressed  as  part  of  that  extension. 

It  may  be  that  functions  such  as  systemO  and popen{),  currently  being  considered 
for  ISO/IEC  9945-2  [B36],  will  have  to  perform  some  of  these  operations. 

The  introduction  of  underlying  functions  allows  generic  reference  to  errno  values 
returned  by  those  functions  and  also  to  other  side  effects  (as  required  in  the  han¬ 
dles  discussion  above).  It  is  not  intended  to  specify  implementation,  although 
many  implementations  may  in  fact  use  those  functions.  The  C  Standard  {2}  says 
very  little  about  errno  in  the  context  of  stdio.  In  the  more  restricted  POSIX.1 
environment,  providing  a  reasonable  set  of  errno  values  become  possible. 


B.8.2.3.1  fopen  () 

There  is  no  additional  rationale  provided  for  this  subclause. 

B.8.2.3.2  fclose  () 

The  fclose ()  function  is  required  to  synchronize  the  buffer  pointer  with  the  file 
pointer  (unless  it  already  is,  which  would  be  the  case  at  EOF).  Functionality 
equivalent  to 

f  seek  (stream,  f tell  (stream) ,  seek_set) 

does  this  nicely.  The  exception  for  devices  incapable  of  seeking  is  an  obvious 
requirement,  but  the  implication  is  that  there  is  no  way  to  reliably  read  a  buffered 
pipe  and  hand  off  handles.  This  is  the  situation  in  historical  implementations 
and  is  inherent  in  any  “read-ahead”  buffering  scheme.  This  limitation  is  also 
reflected  in  the  handle  hand-off  rules. 
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4411  Note  that  the  last  byte  read  from  a  stream  and  the  last  byte  read  from  an  open 

4412  file  description  are  not  necessarily  the  same;  in  most  cases  the  open  file 

4413  description’s  pointer  will  be  past  that  of  the  stream  because  of  the  stream’s  read- 

4414  ahead. 

4415  B.8.2.3.3  freopeni) 

4416  There  is  no  additional  rationale  provided  for  this  subclause. 

4417  B.8.2.3.4  fflushi) 

4418  There  is  no  additional  rationale  provided  for  this  subclause.  | 

4419  B.8.2.3.5  fgetc  ( ),  fgets  ( ),  fread  ( ),  getc  ( ),  getchari ),  gets  ( ),  scanfi ),  f scanfi ) 

4420  There  is  no  additional  rationale  provided  for  this  subclause. 

4421  B.8.2.3.6  fputci),  fputsi),  /write (), putc(), putchar(), puts (), print f(), 

4422  vprintfi),  vfprintfi) 

4423  There  is  no  additional  rationale  provided  for  this  subclause. 

4424  B.8.2.3.7  fseek  ( ),  rewind ( ) 

4425  The  fseek ()  function  must  operate  as  specified  to  make  the  case  where  seeking  is 

4426  being  done  work.  The  key  requirement  is  to  avoid  an  optimization  such  that  an 

4427  fseek ()  would  not  result  in  an  Iseek ()  if  the  fseeki)  pointed  within  the  current 

4428  buffer.  This  optimization  is  valuable  in  general,  so  it  is  only  required  after  an 

4429  fflushi). 

4430  B.8.2.3.8  perror () 

4431  There  is  no  additional  rationale  provided  for  this  subclause. 

4432  B.8.2.3.9  tmpfilei) 

4433  There  is  no  additional  rationale  provided  for  this  subclause. 

4434  B.8.2.3.10  ftelli) 

4435  In  append  mode,  a  fflushi)  will  change  the  seek  pointer  because  of  possible  writes  | 

4436  by  other  processes  on  the  same  file.  An  fseeki, )  reflects  the  underlying  file’s  file  | 

4437  offset,  which  is  not  necessarily  the  end  of  the  file.  Implementors  should  be  aware  | 

4438  that  the  operating  system  itself  (not  some  in-memory  approximation)  of  the  file  | 

4439  offset  should  be  queried  when  in  append  mode.  | 

4440  B.8.2.3.11  Error  Reporting 

4441  POSIX.  1  intentionally  does  not  require  that  all  errors  detected  by  the  underlying  | 

4442  functions  be  detected  by  the  functions  listed  here.  There  are  many  reasonable  | 

4443  cases  where  this  might  not  occur;  for  example,  many  of  the  functions  with  writei)  | 

4444  as  an  underlying  function  might  not  detect  a  number  of  error  conditions  in  cases  | 

4445  where  they  simply  buffer  output  for  a  subsequent  flush.  | 
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4446  [ENOMEM]  was  considered  for  addition  as  an  explicit  possible  error  because  most 

4447  implementations  use  malloc ().  This  was  not  done  because  the  scope  does  not 

4448  include  “out  of  resource”  errors.  Nevertheless  this  is  the  most  likely  error  to  be 

4449  added  to  the  possible  error  conditions.  Other  implementation-defined  errors,  par- 

4450  ticularly  in  the  f*open{)  family,  are  to  be  expected,  and  the  generic  rules  about 

4451  adding  (or  deleting)  possible  errors  apply,  except  that  it  is  expected  that 

4452  implementation-defined  changes  in  the  error  set  returned  by  open  ()  would  also 

4453  apply  to  fopen ()  [unless  the  condition  cannot  possibly  happen  in  fopenO,  which 

4454  may  be  possible,  but  appears  unlikely]. 

4455  B.8.2.3.12  exit (),  abort () 

4456  POSIX.l  intends  that  processing  related  to  the  abortO  function  will  occur  unless  | 

4457  “the  signal  SIGABRT  is  being  caught,  and  the  signal  handler  does  not  return,”  as  | 

4458  defined  by  the  C  Standard  {2}.  This  processing  includes  at  least  the  effect  of  | 

4459  fclose ()  on  all  open  streams,  and  the  default  actions  defined  for  SIGABRT.  | 

4460  The  abortO  function  will  override  blocking  or  ignoring  the  SIGABRT  signal.  | 

4461  Catching  the  signal  is  intended  to  provide  the  application  writer  with  a  portable  | 

4462  means  to  abort  processing,  free  from  possible  interference  from  any  | 

4463  implementation-provided  library  functions.  | 

4464  Note  that  the  term  “program  termination”  in  the  C  Standard  {2}  is  equivalent  to  | 

4465  “process  termination”  in  POSIX.l.  | 

4466  B.8.2.4  Operations  on  Files  —  the  remove  ()  Function 

4467  There  is  no  additional  rationale  provided  for  this  subclause. 

4468  B.8.3  Other  C  Language  Functions 

4469  B.8.3. 1  Nonlocal  Jumps 

4470  The  C  Standard  {2}  specifies  various  restrictions  on  the  usage  of  the  setjmpO 

4471  macro  in  order  to  permit  implementors  to  recognize  the  name  in  the  compiler  and 

4472  not  implement  an  actual  function.  These  same  restrictions  apply  to  the  sig- 

4473  setjmp  ( )  macro. 

4474  There  are  processors  that  cannot  easily  support  these  calls,  but  this  was  not  con-  | 

4475  sidered  a  sufficient  reason  to  exclude  them. 

4476  The  distinction  between  setjmpO/ longjmpO  and  sigsetjmpO/siglongjmpO  is  only 

4477  significant  for  programs  that  use  the  sigactionO,  sigprocmaskO,  or  sigsuspendO 

4478  functions.  Since  earlier  implementations  did  not  have  signal  masks,  only  a  single 

4479  pair  was  provided. 

4480  4.2BSD  and  4.3BSD  systems  provide  functions  named  jsetjmpO  and  _longjmp O 

4481  that,  together  with  setjmp ()  and  longjmpO,  provide  the  same  functionality  as  sig- 

4482  setjmpO  and  siglongjmpO-  On  those  systems,  setjmpO  and  longjmpO  save  and 

4483  restore  signal  masks,  while  _setjmpO  and  JongjmpO  do  not.  On  System  V 

4484  Release  3  and  in  corresponding  issues  of  the  SVID  (B39},  setjmpO  and  longjmpO 

4485  are  explicitly  defined  not  to  save  and  restore  signal  masks.  In  order  to  permit 
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existing  practice  in  both  cases,  the  relation  of  setjmpi)  and  longjmp ()  to  signal  | 
masks  is  not  specified,  and  a  new  set  of  functions  is  defined  instead.  | 

B.8.3.2  Set  Time  Zone 

There  is  no  additional  rationale  provided  for  this  subclause. 

B.8.3.3  Omitted  Memory  Management  | 

The  brki)  and  sbrki)  functions  frequently  were  proposed  for  inclusion  in  POSIX.1,  | 
but  they  were  excluded  deliberately.  See  also  B.1.1.  The  rationale  for  including  | 
them  is  usually  addressed  to  the  argument  that  it  is  the  sbrki )  primitive  that  | 
makes  it  possible  to  implement  some  more  general  heap  management  system,  | 
such  as  that  provided  for  C  by  malloci).  The  need  for  such  functionality  is  fully  | 
understood,  but  specifying  it  as  a  part  of  a  standard  would  have  the  effect  of  limit-  | 
ing  the  number  of  architectures  that  could  support  POSIX.1.  It  might  also  con-  | 
strain  languages  whose  memory-management  model  was  not  served  by  the  sbrki)  \ 
model. 

Memory  management  is  not  excluded  from  POSIX.1:  POSIX.1  relies  on  the  | 
language  to  provide  it,  and  in  the  C  binding  (as  reflected  in  Section  8)  it  is  pro-  | 
vided  by  malloci).  It  would  be  provided  by  newi)  in  Pascal.  In  a  language  like  | 
FORTRAN,  which  does  not  supply  memory  management  to  the  user,  it  would  be  | 
undesirable  to  force  the  language  binding  to  attempt  to  include  such  a  function.  | 
It  is  reasonable  to  imagine  a  language  that  required  a  more  powerful  primitive  | 
than  sbrki)  to  be  implemented,  and  standardizing  sbrki)  would  only  constrain  | 
such  future  languages.  | 

POSIX.1  is  silent  about  mixed  languages.  Mixing  languages  that  provide  incompa-  | 
tible  memory-management  mechanisms  can  yield  unpredictable  results.  Future  | 
standards  that  address  mixing  of  languages  should  consider  this  issue.  | 

Architectures  that  could  not  support  sbrki)  are  also  a  limiting  factor.  In  particu-  | 
lar,  architectures  that  do  not  present  a  model  of  a  single  linear  address  space  | 
would  be  severely  constrained  by  sbrki),  but  are  not  so  constrained  by  malloci)  or  | 
newi).  I 

Each  language  should  specify  the  memory-management  primitives  best  suited  to  | 
that  language.  Whether  the  implementor  chooses  to  use  a  more  primitive  | 
mechanism  to  implement  that,  or  the  implementor  chooses  to  directly  implement  | 
the  language  function  in  the  kernel,  is  not  a  proper  concern  of  the  developers  of  | 
POSIX.1,  nor  should  it  be  for  any  portable  application.  An  application  that  | 
presumes  the  sbrki)  model  of  memory  management  will  not  port  to  all  architec-  | 
tures  in  any  case,  for  the  same  reasons  that  sbrki)  itself  does  not  work  on  those  | 
architectures.  No  true  gain  in  application  portability  would  be  achieved  by  man-  | 
dating  such  an  interface.  This  implies  that  an  implementor  of  software  that  | 
wishes  to  port  to  multiple  platforms  and  that  attempts  to  implement  its  own  | 
memory  management  rather  than  relying  on  language-supplied  functions  must  be  | 
prepared  to  deal  with  multiple  platform-supplied  primitives  and,  because  it  is  | 
doing  its  own  memory  management  inherently,  cannot  be  considered,  or  be  made  | 
to  be,  portable  in  that  regard. 
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4529  B.9  System  Databases 

4530  At  one  time,  this  section  was  entitled  Passwords,  but  this  title  was  changed  as  all  | 

4531  references  to  a  “password  file”  were  changed  to  refer  to  a  “user  database.” 

4532  B.9.1  System  Databases 

4533  There  are  no  references  in  POSIX.l  to  a  passwd  file  or  a  group  file,  and  there  is  no 

4534  requirement  that  the  group  or  passwd  databases  be  kept  in  files  containing  edit-  | 

4535  able  text.  Many  large  timesharing  systems  use  passwd  databases  that  are  | 

4536  hashed  for  speed.  Certain  security  classifications  prohibit  certain  information  in 

4537  the  passwd  database  from  being  publicly  readable. 

4538  The  term  “encoded”  is  used  instead  of  “encrypted”  in  order  to  avoid  the  implemen- 

4539  tation  connotations  (such  as  reversibility  or  use  of  a  particular  algorithm)  of  the 

4540  latter  term. 

4541  The  getgrentO,  setgrentO,  endgrentO,  getpwentO,  setpwenti) ,  and  endpwenti) 

4542  functions  are  not  included  in  POSIX.l  because  they  provide  a  linear  database 

4543  search  capability  that  is  not  generally  useful  [the  getpwuidO,  getpwnamO,  get- 

4544  grgidi),  and  getgrnamO  functions  are  provided  for  keyed  lookup]  and  because  in 

4545  certain  distributed  systems,  especially  those  with  different  authentication 

4546  domains,  it  may  not  be  possible  or  desirable  to  provide  an  application  with  the 

4547  ability  to  browse  the  system  databases  indiscriminately. 

4548  A  change  from  historical  implementations  is  that  the  structures  used  by  these  | 

4549  functions  have  fields  of  the  types  gid_t  and  uidj,  which  are  required  to  be  defined  | 

4550  in  the  header  <sys/types  .  h>.  POSIX.1  has  not  changed  the  synopses  of  these  | 

4551  functions  to  require  the  inclusion  of  this  header,  since  that  would  invalidate  a  | 

4552  large  number  of  existing  applications.  Implementations  must  ensure  that  these  | 

4553  types  are  defined  by  the  inclusion  of  <grp .  h>  and  <pwd .  h>,  respectively,  without  | 

4554  imposing  any  namespace  pollution  or  errors  from  redefinition  of  types. 

4555  POSIX.1  is  silent  about  the  content  of  the  strings  containing  user  or  group  names.  | 

4556  These  could  be  digit  strings.  POSIX.1  is  also  silent  as  to  whether  such  digit  | 

4557  strings  bear  any  relationship  to  the  corresponding  (numeric)  user  or  group  ID. 

4558  B.9.2  Database  Access 

4559  B.9.2. 1  Group  Database  Access 

4560  There  is  no  additional  rationale  provided  for  this  subclause. 

4561  B.9.2.2  User  Database  Access 

4562  There  is  no  additional  rationale  provided  for  this  subclause. 
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B.10  Data  Interchange  Format 


B.10.1  Archive/Interchange  File  Format 

There  are  three  areas  of  interest  associated  with  file  interchange: 

(1)  Media.  There  are  other  existing  standards  that  define  the  media  used  for 
data  interchange. 

(2)  User  Interface.  This  rightfully  should  be  in  the  shell  and  utilities  stan-  | 

dard,  under  development  as  ISO/IEC  9945-2  {B36}.  j 

(3)  Format  of  the  Data.  None  of  the  groups  currently  developing  POSIX  stan-  | 
dards  address  topics  that  match  this  area.  The  groups  felt  that  this  area  | 
is  closest  to  the  types  of  things  that  should  be  in  the  POSIX.  1  document,  | 
as  the  level  of  that  document  most  closely  matches  the  level  of  data  | 
required. 

There  are  two  programs  in  wide  use  today:  tar  and  cpio.  There  are  many  sup¬ 
porters  for  each  program.  Four  options  were  considered  for  POSIX.1: 

(1)  Make  both  formats  optional.  This  was  considered  unacceptable  because 
it  does  not  allow  any  portable  method  for  data  interchange. 

(2)  Require  one  format. 

(3)  Require  one  format  with  the  other  optional. 

(4)  Require  both  formats. 

Both  the  Extended  cpio  and  the  Extended  tar  Formats  are  required  by  POSIX.1. 

There  are  a  number  of  concerns  about  defining  extensions  that  are  known  to  be 
required  by  historical  implementations.  Failure  to  specify  a  consistent  method  to  | 
implement  these  extensions  will  limit  portability  of  the  data  and,  more  impor¬ 
tantly,  will  create  confusion  if  these  extensions  are  later  standardized. 

Two  of  these  extensions  that  should  be  documented  are  symbolic  links,  which  | 
were  defined  by  4.2BSD  and  4.3BSD  systems,  and  high-performance  (or  contigu¬ 
ous)  files,  which  exist  in  a  number  of  implementations  and  are  now  being  con¬ 
sidered  for  future  amendments  to  POSIX.1.  | 

By  defining  these  extensions,  implementors  are  able  to  recognize  these  features 
and  take  appropriate  implementation-defined  actions  for  these  files.  For  example, 
a  high-performance  file  could  be  converted  to  a  regular  file  if  the  system  did  not 
support  high-performance  files;  symbolic  links  might  be  replaced  by  normal  hard 
links. 

The  policy  of  not  defining  user  interfaces  to  utilities  preempted  any  description  of  | 
a  tar  or  cpio  command.  The  behavior  of  the  former  command  was  described  in 
some  detail  in  previous  drafts. 

The  possibilities  for  transportable  media  include,  but  are  not  limited  to 

(1)  12,7  mm  (0,5  in)  magnetic  tape,  9  track,  63  bpmm  (1 600  bpi)  | 

(2)  12,7  mm  (0,5  in)  magnetic  tape,  9  track,  246  cpmm  (6  250  cpi) 
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(3)  QIC-11,  6,30  mm  (0,25  in)  streamer  tape  | 

(4)  QIC-24,  6,30  mm  (0,25  in)  streamer  tape  | 

(5)  130  mm  (5,25  in)  diskettes,  9  512-byte  sectors/track,  3,8  tpmm  (96  tpi)  | 

(6)  130  mm  (5,25  in)  diskettes,  9  512-byte  sectors/track,  1,9  tpmm  (48  tpi)  | 

When  selecting  media,  issues  such  as  character  frame  size  also  need  to  be  | 
addressed.  The  easiest  environment  for  interchange  occurs  when  8-bit  frames  are 
used. 

The  utilities  are  not  restricted  to  work  only  with  transportable  media:  existing  | 
related  utilities  are  often  used  to  transport  data  from  one  place  to  another  in  the 
file  hierarchy. 

The  formats  are  included  to  provide  implementation-independent  ways  to  move 
files  from  one  system  to  another  and  also  to  provide  ways  for  a  user  to  save  data 
on  a  transportable  medium  to  be  restored  at  a  later  date.  Unfortunately,  these 
two  goals  can  contradict  each  other,  as  system  security  problems  are  easy  to  find 
in  tape  systems  if  they  are  not  protected.  Thus,  there  are  strict  requirements 
about  how  the  mechanism  to  copy  files  shall  react  when  operated  by  both 
privileged  and  nonprivileged  users.  The  general  concept  is  that  a  privileged  (his¬ 
torically  using  the  ISUID  bit  in  the  file’s  mode  with  the  owner  UID  of  the  file  set  to 
super-user)  version  of  the  utility  (or  one  operated  by  a  privileged  user)  can  be 
used  as  a  save/restore  scheme,  but  a  nonprivileged  version  is  used  to  interpret 
media  from  a  different  system  without  compromising  system  security. 

Regardless  of  the  archive  format  used,  guidelines  should  be  observed  when  writ¬ 
ing  tapes  to  be  read  on  other  systems.  Assuming  the  target  system  conforms  to 
POSIX.1,  archives  created  should  only  use  definitions  found  in  POSIX.l  (e.g.,  file 
types,  minimum  values  as  found  in  Section  2)  and  should  only  use  relative  path-  | 
names  (i.e.,  no  leading  slash). 

Both  tar  and  cpio  formats  have  traditionally  been  used  for  both  exchange  of 
information  and  archiving.  These  formats  have  a  number  of  features  that  facili¬ 
tate  archiving,  for  example,  the  ability  to  store  information  about  a  file  that  is  a 
device.  POSIX.1  does  not  assume  this  kind  of  data  is  portable.  It  is  intended  that 
these  formats  provide  for  the  portable  exchange  of  source  information  between 
dissimilar  systems.  This  requires  specification  of  the  character  set  to  be  used  | 
(ISO/IEC  646  {1})  when  these  formats  are  used  to  write  source  information.  The  | 
1990  version  of  ISO/IEC  646  {1}  IRV  was  selected  as  the  international  character  set  | 
that  corresponds  most  directly  to  the  ASCII  set  used  in  many  historical  implemen-  | 
tations.  The  1990  version  was  chosen  over  the  1983  version  because  it  defines 
'  $ '  as  the  currency  symbol  in  the  IRV,  as  opposed  to  the  starburst-like  generic 
currency  symbol.  Note  that  ISO/IEC  646  {1}  is  a  safe  lowest-common-denominator  | 
character  set  and  that  interchange  of  larger  character  sets  is  permitted  by  mutual 
agreement.  Using  any  other  character  set  (such  as  ISO  8859-1  {B34}  or  some  mul¬ 
tibyte  character  set)  reduces  the  number  of  machines  to  which  interchange  is 
guaranteed. 

All  data  written  by  format-creating  utilities  and  read  by  format-reading  utilities 
is  an  ordered  stream  of  bytes.  The  first  byte  of  the  stream  should  be  first  on  the 
medium,  the  second  byte  second,  etc.  On  systems  where  the  hardware  swaps 
bytes  or  otherwise  rearranges  the  byte  stream  on  output  or  input,  the 
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implementor  of  these  utilities  must  compensate  for  this  so  that  the  data  on  the 
storage  device  retains  its  ordered  nature. 

POSIX.  1  describes  two  different  formats  for  data  archiving  and  interchange.  | 
Strong  support  for  both  formats  was  evident  through  the  balloting  process.  This  | 
is  a  clear  indication  of  the  need  for  both  formats  due  to  existing  practice.  The  bal¬ 
loting  process  also  defined  a  number  of  deficiencies  of  each  format.  The  strong 
support  indicates  that  these  deficiencies  are  not  sufficient  to  remove  either  format 
from  POSIX.l,  but  will  need  to  be  addressed  in  future  amendments  to  POSIX.l.  It 
was  not  practical  to  remedy  these  deficiencies  during  the  balloting  process.  Con¬ 
siderable  thought  and  review  must  occur  before  making  any  changes  to  these  for¬ 
mats.  It  was  felt  that  the  best  solution  is  to  advise  implementors  and  application 
writers  of  these  deficiencies  by  documenting  them  in  the  rationale  and  to  include 
both  formats  in  POSIX.  1. 

The  developers  of  POSIX  1  recognize  the  desirability  for  migration  toward  one  | 
common  format  and  have  been  made  aware  of  some  strong  inputs  to  consider  both  | 
formats  in  light  of  existing  practice,  current  technology  trends,  and  the  POSIX  | 
standards  activities  such  as  security  and  high-performance  systems,  and  to  | 
develop  one  format  that  is  technically  superior.  This  format  will  be  incorporated  | 
into  a  future  amendment  to  POSIX.l  when  it  is  developed.  | 

The  deficiencies  that  have  been  identified  in  the  existing  formats  are  as  follows. 
The  size  of  a  file  link  is  limited  to  100  characters  in  tar.  A  number  of  fields  in 
the  cpio  header  (c Jilesize,  cjdev,  c_ino,  cjnode,  and  c_rdev)  are  too  short  to 
support  values  that  POSIX.l  allows  these  fields  to  contain.  Some  existing  imple¬ 
mentations  and  current  trends  in  development  will  require  the  ability  to 
represent  even  larger  values  in  these  fields.  The  cpio  format  does  not  provide  a 
mechanism  to  represent  the  user  and  group  IDs  symbolically,  and  a  range  of 
implementation-defined  file  types  have  not  been  reserved  for  the  user.  The  cpio 
format  specification  does  not  reserve  any  formats  for  implementation-defined 
usage.  The  extensions  that  have  been  made  to  cpio  for  POSIX.  1  are  compatible 
with  existing  versions  of  cpio.  Correction  of  some  of  these  deficiencies  would 
make  existing  versions  of  cpio  behave  unpredictably.  When  these  changes  are 
made  the  cpio  magic  number  will  have  to  be  changed. 

This  clause  uses  the  term  file  name;  note  that  filename  and  file  name  are  not  | 
synonyms;  the  latter  is  a  synonym  for  pathname,  in  that  it  includes  the  slashes 
between  filenames. 

In  earlier  drafts,  the  word  “local”  was  used  in  the  context  of  “file  system”  and  was 
taken  (incorrectly)  to  be  related  to  “remotely  mounted  file  system.”  This  was  not 
intended.  The  term  “(local)  file  system”  refers  to  the  file  hierarchy  as  seen  by  the 
utilities,  and  “local”  was  removed  because  of  this  confusion. 

B.10.1.1  Extended  tar  Format 

The  original  model  for  this  facility  is  the  4.3BSD  or  Version  7  tar  program  and 
format,  but  the  format  given  here  is  an  extension  of  the  traditional  tar  format. 
The  name  USTAR  was  adopted  to  reflect  this. 

This  description  reflects  numerous  enhancements  over  previous  versions.  The 
goal  of  these  changes  was  not  only  to  provide  the  functional  enhancements 
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desired,  but  also  to  retain  compatibility  between  new  and  old  versions.  This  com¬ 
patibility  has  been  retained.  Archives  written  using  the  old  archive  format  are 
compatible  with  the  new  format.  Archives  written  using  this  new  format  may  be 
read  by  applications  designed  to  use  the  old  format  as  long  as  the  functional 
enhancements  provided  here  are  not  used.  This  means  the  user  is  limited  to 
archiving  only  regular  type  files  and  nonsymbolic  links  to  such  files. 

Implementors  should  be  aware  that  the  previous  file  format  did  not  include  a 
mechanism  to  archive  directory  type  files.  For  this  reason,  the  convention  of 
using  a  file  name  ending  with  slash  was  adopted  to  specify  a  directory  on  the 
archive. 

The  total  size  of  the  name  and  prefix  fields  have  been  set  to  meet  the  minimum 
requirements  for  {PATH_MAX}.  If  a  pathname  will  fit  within  the  name  field,  it  is 
recommended  that  the  pathname  be  stored  there  without  the  use  of  the  prefix 
field.  Although  the  name  field  is  known  to  be  too  small  to  contain  {PATH_MAX} 
characters,  the  value  was  not  changed  in  this  version  of  the  archive  file  format  to 
retain  backward  compatibility,  and  instead  the  prefix  was  introduced.  Also, 
because  of  the  earlier  version  of  the  format,  there  is  no  way  to  remove  the  restric¬ 
tion  on  the  linkname  field  being  limited  in  size  to  just  that  of  the  name  field. 

The  size  field  is  required  to  be  meaningful  in  all  implementation  extensions, 
although  it  could  be  zero.  This  is  required  so  that  the  data  blocks  can  always  be 
properly  counted. 

It  is  suggested  that  if  device  special  files  need  to  be  represented  that  cannot  be 
represented  in  the  standard  format  that  one  of  the  extension  types  ('A'-'z')  be 
used,  and  that  the  additional  information  for  the  special  file  be  represented  as 
data  and  be  reflected  in  the  size  field. 

Attempting  to  restore  a  special  file  type,  where  it  is  converted  to  ordinary  data 
and  conflicts  with  an  existing  file  name,  need  not  be  specially  detected  by  the  util¬ 
ity.  If  run  as  an  ordinary  user,  a  format-reading  utility  should  not  be  able  to 
overwrite  the  entries  in,  for  example,  /dev  in  any  case  (whether  the  file  is  con¬ 
verted  to  another  type  or  not).  If  run  as  a  privileged  user,  it  should  be  able  to  do 
so,  and  it  would  be  considered  a  bug  if  it  did  not.  The  same  is  true  of  ordinary 
data  files  and  similarly  named  special  files;  it  is  impossible  to  anticipate  the 
user’s  needs  (who  could  really  intend  to  overwrite  the  file),  so  the  behavior  should 
be  predictable  (and  thus  regular)  and  rely  on  the  protection  system  as  required. 

The  values  '2'  and  '7'  in  the  typeflag  field  are  intended  to  define  how  symbolic 
links  and  contiguous  files  can  be  stored  in  a  tar  archive.  POSIX.1  does  not 
require  the  symbolic  link  or  contiguous  file  extensions,  but  does  define  a  standard 
way  of  archiving  these  files  so  that  all  conforming  systems  can  interpret  these  file 
types  in  a  meaningful  and  consistent  manner.  On  a  system  that  does  not  support 
extended  file  types,  the  format-interpreting  utility  should  do  the  best  it  can  with 
the  file  and  go  on  to  the  next. 

B.10.1.2  Extended  cpio  Format 

The  model  for  this  format  is  the  existing  System  V  cpio  -c  data  interchange  for¬ 
mat.  This  model  documents  the  portable  version  of  cpio  format  and  not  the 
binary  version.  It  has  the  flexibility  to  transfer  data  of  any  type  described  within 
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4738  the  POSIX.  1  standard,  yet  is  extensible  to  transfer  data  types  specific  to  exten- 

4739  sions  beyond  POSIX.1  (e.g.,  symbolic  links  or  contiguous  files).  Because  it 

4740  describes  existing  practice,  there  is  no  question  of  maintaining  upward 

4741  compatibility. 

4742  This  subclause  does  not  standardize  behavior  for  the  utility  when  the  file  type  is  | 

4743  not  understood  or  supported.  It  is  useful  for  the  utility  to  report  to  the  user  what- 

4744  ever  action  is  taken  in  this  case,  though  POSIX.1  neither  requires  nor  recommends 

4745  this. 

4746  B.10.1.2.1  cpio  Header 

4747  There  has  been  some  concern  that  the  size  of  the  cjno  field  of  the  header  is  too 

4748  small  to  handle  those  systems  that  have  very  large  i-node  numbers.  However,  the 

4749  cjno  field  in  the  header  is  used  strictly  as  a  hard  link  resolution  mechanism  for 

4750  archives.  It  is  not  necessarily  the  same  value  as  the  i-node  number  of  the  file  in 

4751  the  location  from  which  that  file  is  extracted. 


4752  B.10.1.2.2  cpio  File  Name 

4753  For  most  historical  implementations  of  the  cpio  utility,  {PATH_MAX}  bytes  can  be 

4754  used  to  describe  the  pathname  without  the  addition  of  any  other  header  fields  (the 

4755  null  byte  would  be  included  in  this  count).  {PATH_MAX}  is  the  minimum  value  for 

4756  pathname  size,  documented  as  256  bytes  in  Section  2.  However,  an  implementa-  | 

4757  tion  may  use  cjiamesize  to  determine  the  exact  length  of  the  pathname.  With  the 

4758  current  description  of  the  cpio  header,  this  pathname  size  can  be  as  large  as  a 

4759  number  that  is  described  in  six  octal  digits. 


4760  B.10.1.2.3  cpio  File  Data 

4761  There  is  no  additional  rationale  provided  for  this  subclause. 

4762  B.10.1.2.4  cpio  Special  Entries 

4763  These  are  provided  to  maintain  backward  compatibility. 


4764  B.10.1.2.5  cpio  Values 


4765  Three  values  are  documented  under  the  cjnode  field  values  to  provide  for  extensi- 

4766  bility  for  known  file  types: 


4767  0110000 

4768 

4769 

4770 


Reserved  for  contiguous  files.  The  implementation  may  treat 
the  rest  of  the  information  for  this  archive  like  a  regular  file.  If 
this  file  type  is  undefined,  the  implementation  may  create  the 
file  as  a  regular  file. 


4771 

4772 

4773 

4774 

4775 

4776 


0120000  Reserved  for  files  with  symbolic  links.  The  implementation 
may  store  the  link  name  within  the  data  portion  of  the  file.  If 
this  type  is  undefined,  the  implementation  may  not  know  how 
to  link  this  file  or  be  able  to  understand  the  data  section.  The 
implementation  may  decide  to  ignore  this  file  type  and  output  a 
warning  message. 
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0140000  Reserved  for  sockets.  If  this  type  is  undefined  on  the  target 
system,  the  implementation  may  decide  to  ignore  this  file  type 
and  output  a  warning  message. 

This  provides  for  extensibility  of  the  cpio  format  while  allowing  for  the  ability  to 
read  old  archives.  Files  of  an  unknown  type  may  be  read  as  “regular  files”  on 
some  implementations.  On  a  system  that  does  not  support  extended  file  types, 
the  format-interpreting  utility  should  do  the  best  it  can  with  the  file  and  go  on  to 
the  next. 

B.10.1.3  Multiple  Volumes 

Multivolume  archives  have  been  introduced  in  a  manner  that  has  become  a  de 
facto  standard  in  many  implementations.  Though  it  is  not  required  by  POSIX.1, 
classical  implementations  of  the  format-reading  and  -creating  utility,  upon  read¬ 
ing  logical  end-of-file,  check  to  see  if  an  error  channel  is  open  to  a  controlling  ter¬ 
minal.  The  utility  then  produces  a  message  requesting  a  new  medium  to  be  made 
available.  The  utility  waits  for  a  new  medium  to  be  made  available  by  attempting 
to  read  a  message  to  restart  from  the  controlling  terminal.  In  all  cases,  the  com¬ 
munication  with  the  controlling  terminal  is  in  an  implementation-defined 
manner. 

This  subclause  (10.1.3)  is  intended  to  handle  the  issue  of  multiple  volume  | 
archives.  Since  the  end-of-medium  and  transition  between  media  are  not  properly 
part  of  POSIX.1,  the  transition  is  described  in  terms  of  files;  the  word  “file”  is  used 
in  a  very  broad,  but  correct,  sense — a  tape  drive  is  a  file.  The  intent  is  that  files 
will  be  read  serially  until  the  end-of-archive  indication  is  encountered  and  that 
file  or  media  change  will  be  handled  by  the  utilities  in  an  implementation-defined 
manner. 

Note  that  there  was  an  issue  with  the  representation  of  this  on  magnetic  tape, 
and  POSIX.1  is  intended  to  be  interpreted  such  that  each  byte  of  the  format  is 
represented  on  the  media  exactly  once.  In  some  current  implementations,  it  is 
not  deterministic  whether  encountering  the  end-of-medium  reflector  foil  on  mag¬ 
netic  tape  during  a  write  will  yield  an  error  during  a  subsequent  read  ()  of  that 
record,  or  if  that  record  is  actually  recorded  on  the  tape.  It  is  also  possible  that 
read()  will  encounter  the  end-of-medium  when  end-of-medium  was  not  encoun¬ 
tered  when  the  data  was  written.  This  has  to  do  with  conditions  where  the  end  of 
[magnetic)  record  is  in  such  a  position  that  the  reflector  foil  is  on  the  verge  of 
being  detected  by  the  sensor  and  is  detected  during  one  operation  and  not  on  a 
later  one,  or  vice  versa. 

An  implementation  of  the  format-creating  utility  must  assure  when  it  writes  a 
record  that  the  data  appears  on  the  tape  exactly  once.  This  implies  that  the  pro¬ 
gram  and  the  tape  driver  work  in  concert.  An  implementation  of  the  format¬ 
reading  utility  must  assure  that  an  error  in  a  boundary  condition  described  above 
will  not  cause  loss  of  data. 

The  general  consensus  was  that  the  following  would  be  considered  as  correct 
operation  of  a  tape  driver  when  end-of-medium  is  detected: 

(1)  During  writing,  either 
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(a)  The  record  where  the  reflector  spot  was  detected  is  backspaced  over 
by  the  driver  so  that  the  trailing  tape  mark  that  will  be  written  on 
close ()  will  overwrite.  Writing  the  tape  mark  should  not  yield  an 
end-of-medium  condition,  or 

(b)  The  condition  is  reported  as  an  error  on  the  write  ()  following  the 
one  where  the  end-of-medium  is  detected  (the  one  where  the  end- 
of-medium  is  actually  detected  completing  successfully).  No  data 
will  be  actually  transferred  on  the  write  ()  reporting  the  error.  The 
subsequent  close  ()  would  write  a  tape  mark  following  the  last 
record  actually  written.  Writing  the  tape  mark,  and  writing  any 
subsequent  records,  should  not  yield  any  end-of-medium  conditions. 

[The  latter  behavior  permits  the  implementation  of  ANSI  standard  labels 
because  several  records  (the  trailer  records)  can  be  written  after  the  end- 
of-medium  indications.  It  also  permits  dealing  with,  for  example,  COBOL 
“ON”  statements.] 

(2)  During  reading,  the  end-of-medium  indicator  is  simply  ignored,  presum¬ 
ing  that  a  tape  mark  (end-of-file)  will  be  recorded  on  the  magnetic 
medium  and  that  the  reflector  foil  was  advisory  only  to  the  write  (). 

Systems  where  these  conditions  are  not  met  by  the  tape  driver  should  assure  that 
the  format-creating  and  -reading  utilities  assure  proper  representation  and 
interpretations  of  the  files  on  the  media  in  a  way  consistent  with  the  above  recom¬ 
mendations. 

The  typical  failures  on  systems  that  do  not  meet  the  above  conditions  are  either 

(1)  To  leave  the  record  written  when  the  end-of-medium  is  encountered  on 
the  tape,  but  to  report  that  it  was  not  written.  The  format-creating  util¬ 
ity  would  then  rewrite  it,  and  then  the  format-reading  utility  could  see 
the  record  twice  if  the  end-of-medium  is  not  sensed  during  the  read 
operations,  or 

(2)  The  write()  occurs  uneventfully,  but  the  readi)  senses  the  error  and  does 
not  actually  see  the  data,  causing  a  record  to  be  omitted. 

Nothing  in  POSIX.1  requires  that  end-of-medium  be  determined  by  anything  on 
the  medium  itself  (for  example,  a  predetermined  maximum  size  would  be  an 
acceptable  solution  for  the  format-creating  utility).  The  format-reading  utility 
must  be  able  to  read{)  tapes  written  by  machines  that  do  use  the  whole  medium, 
however. 

On  media  where  end-of-medium  and  end-of-file  are  reliably  coincident,  such  as 
disks,  end-of-medium  and  end-of-file  can  be  treated  as  synonyms. 

Note  that  partial  physical  records  [corresponding  to  a  single  write  ()]  can  be  writ¬ 
ten  on  some  media,  but  that  only  full  physical  records  will  actually  be  written  to 
magnetic  tape,  given  the  manner  in  which  the  tape  operates. 
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Annex  C 

(informative) 

Header  Contents  Samples 


1  The  material  in  this  informative  annex  serves  as  an  index  to  which  symbols 

2  should  appear  in  which  headers  in  a  system  that  conforms  to  POSIX.1  with  C 

3  Standard  Language-Dependent  System  support. 

4  This  is  only  an  index,  and  any  conflicts  with  the  actual  body  of  any  relevant  stan- 

5  dard  shall  be  resolved  in  favor  of  that  standard.  The  actual  body  of  the  declara- 

6  tion  was  omitted  in  part  because  this  is  an  index  and  in  part  to  avoid  any  possible 

7  conflict  with  the  standards. 

8  Where  it  is  known  that  a  symbol  or  header  is  not  required  for  Common  Usage  C 

9  Language-Dependent  System  support,  the  name  is  followed  by  an  asterisk  (*). 

10  Omission  of  an  asterisk  does  not  imply  that  the  symbol  is  required  for  Common- 

n  Usage  C.  For  Common-Usage  C,  although  the  location  of  symbols  is  typical,  it  is 

12  not  to  be  taken  as  a  requirement:  POSIX.1  is  quite  explicit  that  there  is  no 

13  requirement  except  that  differences  from  the  C  Standard  {2}  be  documented. 

14  Generally,  where  it  is  stated  that  functions  are  defined  in  a  header,  macros  are 

15  permitted  as  acceptable  alternatives  by  both  standards.  See  the  bodies  of  the 

16  standards  for  details. 

17  <assert.h> 

is  The  header  defines  the  macro 

19  assertO 

20  and  makes  reference  to  the  macro 

21  NDEBUG 

22  <ctype.h> 

23  The  header  declares  the  functions 

24  isalnum  ()  isdigitO  islower()  ispunctO  isupper() 

25  isalpha()  isgraphO  isprinti)  isspace  ()  isxdigitO 

26  iscntrli) 


toloweri ) 
toupper() 
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<dirent .h> 

The  header  defines  the  typedef 
DIR 

and  declares  the  structure 
dirent 

with  structure  element  member 
djname 


and  declares  functions 

closedirO  opendir{)  readdirO  rewinddirO 

<errno .h> 

The  header  defines  the  macros 


E2BIG 

EEXIST 

EMLINK 

ENOMEM 

EPERM 

EACCES 

EFAULT 

ENAMETOOLONG 

ENOSPC 

EPIPE 

EAGAIN 

EFBIG 

ENFILE 

ENOSYS 

ERANGE 

EBADF 

EINTR 

ENODEV 

ENOTDIR 

EROFS 

EBUSY 

EINVAL 

ENOENT 

ENOTEMPTY 

ESPIPE 

ECHILD 

EIO 

ENOEXEC 

ENOTTY 

ESRCH 

EDEADLK 

EDOM 

EISDIR 

EMFILE 

ENOLCK 

ENXIO 

EXDEV 

and  declares  the  external  variable 


errno 


<fcntl .h> 

The  header  defines  the  macros 


FD_CLOEXEC 

F_DUPFD 

F_GETFD 

f_getfl 

F_GETLK 

F_RDLCK 


F_SETFD 

F_SETFL 

F_SETLK 

F_SETLKW 

F_UNLCK 

FJWRLCK 


0_ACCM0DE 

0_APPEND 

0_CREAT 

0_EXCL 

0_N0CTTY 


0_N0NBL0CK 

o.rdonly 

0_RDWR 

O.TRUNC 

O.WRONLY 


and  declares  the  structure 


flock 

with  structure  elements 
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59  l Jen  l  _pid  l_start  Ijype  Ijwhence 

60  and  the  functions 


6i  creat  ()  fcntli)  open{) 


62  and  may  contain  the  macros 


63 

SEEK_CUR 

S_IROTH 

S_IRWXU 

S_ISFIFO 

S_IWGRP 

S.IXGRP 

64 

SEEK_END 

SJRUSR 

SJSBLK 

S.ISGID 

SJWOTH 

S_IXOTH 

65 

SEEK_SET 

S_IRWXG 

S_ISCHR 

S_ISREG 

SJWUSR 

S.IXUSR 

66 

SJRGRP 

S.IRWXO 

S_ISDIR 

SJSUID 

67  <float.h>* 

68  The  header  defines  the  macros 


69 

DBL_DIG* 

FLT_EPSILON* 

LDBL_DIG* 

70 

DBL_EPSILON* 

FLT_MANT_D  I G* 

LDBL_EPSILON* 

71 

DBL_MANT_DIG* 

FLT_MAX* 

LDBL_MANT_DIG* 

72 

DBL_MAX* 

FLT_MAX_  1 0_EXP  * 

LDBL_MAX* 

73 

DBL_MAX_10_EXP* 

FLT_MAX_EXP* 

LDBL_MAX_10_EXP* 

74 

DBL_MAX_EXP* 

FLT_MIN* 

LDBL_MAX_EXP* 

75 

DBL_MIN* 

FLT_MIN_1 0_EXP* 

LDBL_MIN* 

76 

DBL_MIN_10_EXP* 

FLT_MIN_EXP* 

LDBL_MIN_10_EXP* 

77 

DBL_MIN_EXP* 

FLT_RADIX* 

LDBL_MIN_EXP* 

78 

FLT_DIG* 

FLT_ROUNDS* 

79  <grp .  h> 

so  The  header  declares  the  structure 


81  group 

82  with  structure  elements 

83  gr_gid  grjnem  grjname 

84  and  the  functions 

85  getgrgidO  getgrnamO 
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86  <limits.h> 

87  The  header  defines  the  macros 


88 

ARG_MAX» 

NGROUPS_MAX 

USHRT_MAX 

89 

CHAR_BIT 

OPEN_MAX* 

_POSIX_ARG_MAX 

90 

CHAR_MAX 

PATH_MAX« 

_POSIX_CHILD_MAX 

91 

CHAR_MIN 

PIPE_BUF* 

_POSIX_LINK_MAX 

92 

CHILD_MAX« 

SCHAR_MAX 

_PO  S  IX_M  AX_C  AN  O  N 

93 

INT_MAX 

SCHAR_MIN 

_POSIX_MAX_INPUT 

94 

INT_MIN 

SHRT_MAX 

_POSIX_NAME_MAX 

95 

LINK_MAX» 

SHRT_MIN 

_POSIX_NGROUPS_MAX 

96 

LONG_MAX 

SSIZE_MAX 

_POSIX_OPEN_MAX 

97 

LONG_MIN 

STREAMJVIAXD 

_POSIX_PATH_MAX 

98 

MAX_CANON* 

TZNAME_MAX 

_POSIX_PIPE_BUF 

99 

MAXJNPUT# 

UCHAR_MAX 

_POSIX_SSIZE_MAX 

100 

MB_LEN_MAX 

UINT_MAX 

_POSIX_STREAM_MAX 

101 

NAME_MAX* 

ULONG_MAX 

_POSIX_TZNAME_MAX 

102  The  macros  marked  with  □  shall  be  omitted  from  climits  .  h>  on  specific  imple- 

103  mentations  where  the  corresponding  value  is  greater  than  or  equal  to  the  stated 

104  minimum,  but  is  indeterminate.  The  macros  marked  with  •  shall  be  omitted  from 

105  <limits.h>  on  specific  implementations  where  the  corresponding  value  is 

106  greater  than  or  equal  to  the  stated  minimum,  but  where  the  value  can  vary 

107  depending  on  the  file  to  which  it  is  applied. 

108  <locala.h> 

109  The  header  defines  the  macros 

no  LC_ALL*  LC_CTYPE*  LC.NUMERIC*  NULL* 

111  LC.COLLATE*  LC  MONETARY*  LC  TIME* 

112  and  declares  the  structure 

113  Iconv* 

114  with  structure  elements 

ns  currency  jsymbol* 

116  decimal  _point* 

117  fracjdigits * 

118  grouping* 

119  int_curr_symbol* 

120  int  Jracjdigits* 

121  and  the  functions 

122  localeconv  ()*  setlc 
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monjdecimal  j ooint* 
mon_grouping* 
mon_thousands_sep  * 
n_cs  precedes* 
n_sep_by_space  * 
n_sign  _posn* 


negative  _sign* 
p_cs  _precedes* 
p  _sep  _by  _space  * 
psign  _posn* 
positive _sign* 
thousands  _sep* 


->cale  ()* 
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<math . h> 

The  header  defines  the  macro 
HUGE.VAL 

and  declares  the  functions 


acos () 

ceil() 

exp  () 

fmod{) 

log  10  () 

powO 

sqrt  () 

asin  () 

cos  () 

fabsO 

frexpi) 

log() 

sinO 

tanO 

atan2( ) 

cosh() 

floor  ( ) 

Idexp  ( ) 

modfO 

sinhO 

tanhO 

atari  () 

<pwd . h> 

The  header  defines  the  structure 
passwd 

with  structure  elements 

pw_dir  pw_gid  pwjiame  pw_shell  pwjiid 
and  declares  the  functions 

getpwnamO  getpwuidi ) 

<set jmp .h> 

The  header  defines  the  types 

jmpjbuf  sigjmpjbuf 
and  declares  the  functions 

longjmp  ()  setjmp  ( )  siglongjmp  ()  sigsetjmp  () 

Note  that  the  C  Standard  {2}  and  this  part  of  ISO/IEC  9945  both  permit  these 
functions  to  be  defined  solely  as  macros. 

<signal .h> 

The  header  defines  the  macros 


SA_NOCLDSTOP 

SIGHUP 

SIGQUIT 

SIGTTIN 

SIG_DFL 

SIGABRT 

SIGILL 

SIGSEGV 

SIGTTOU 

SIG_ERR* 

SIGALRM 

SIGINT 

SIGSTOP 

SIGUSR1 

SIG_IGN 

SIGCHLD 

SIGKILL 

SIGTERM 

SIGUSR2 

SIG_SETMASK 

SIGCONT 

SIGFPE 

SIGPIPE 

SIGTSTP 

SIG.BLOCK 

SIGJJNBLOCK 

and  the  types 
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sig_atomic_t*  sigsetjt 
and  declares  the  structure 


sigaction 


with  structure  elements 


sa  Jlags  sajiandler  sajnask 

and  the  functions 

sigpendingi ) 
sigprocmaskO 
sigsuspendO 


<stddef .h>* 

The  header  defines  the  macros 
NULL*  offsetof* 
and  the  types 

ptrdiffjt*  sizejt*  wcharjt* 

<stdio .h> 

The  header  defines  the  macros 


raise ()* 
sigaction  () 


sigaddsetO 
sigdelseti ) 
sigemptyseti ) 


sigfillseti ) 
sigismemberi ) 
signalO* 


<stdarg.h>* 

The  header  defines  the  macros 


va_arg* 


va  end*  ua  list* 


va  start* 


BUFSIZ 

EOF 

FILENAMEJV1AX* 

L_ctermid 

L_cuserid 


L_tmpnam* 

NULL 

SEEK_CUR 

SEEK_END 

SEEK_SET 


STREAMJvlAX* 

TMP_MAX 

stderr 

stdin 


stdout 

_IOFBF* 

_IOLBF* 

_IONBF* 


NOTE:  The  L_cuserid  symbol  is  permitted  in  this  header,  but  need  not  be  supplied.  See  2.7.2. 

and  the  types 

fposjt*  sizejt 

and  declares  the  type 
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182 

FILE 

183 

and  the  functions 

184 

clearerri ) 

filenoi) 

fsetpos  ()* 

putchar{) 

sprintfi ) 

185 

fclose  () 

fopen() 

ftelli ) 

puts() 

sscanfi ) 

186 

fdopeni) 

fprintfi) 

fwriteO 

remove  () 

tmpfile{) 

187 

feo/X) 

fputci) 

getc() 

rename  () 

tmpnamO 

188 

ferrori ) 

fputsi ) 

getchar( ) 

rewind  () 

ungetc{ ) 

189 

fflushO 

freadi) 

gets() 

scanfi ) 

v  fprintfi  )* 

190 

fgetci) 

freopen  ( ) 

perror{ ) 

setbufO 

vprintfi  )* 

191 

fgetposO* 

fscanfi ) 

printfi ) 

setvbuf{  )* 

vsprintfi  )* 

192 

fgetsi) 

fseek  () 

putc  () 

193 

<stdlib .h> 

194 

The  header  defines  the  macros 

195 

EXIT_FAILURE  MB_CUR_MAX*  RAND_MAX 

196 

EXIT_SUCCESS  NULL 

197 

and  the  types 

198 

div_t* 

Idivjt*  sizejt  wcharj* 

199 

and  declares  the  functions 

200 

abort  () 

bsearchi) 

labsO* 

qsort( ) 

strtolO* 

201 

abs( ) 

calloc  () 

IdivO* 

rand() 

strtoulO* 

202 

atexitO* 

div ()* 

mallocO 

realloc  C 

1  system  ()* 

203 

atof{ ) 

ex  it{ ) 

mblen  ()* 

srandO 

westombsi) * 

204 

atoi() 

free  () 

mb  stowcs  ( )*  strtod  ( )* 

*  wetombi)* 

205 

atoli ) 

getenui) 

mbtowc  () 

* 

206 

<string .h> 

207 

The  header  defines  the  macro 

208 

NULL 

209 

and  the  type 

210 

sizejt 
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223 
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and  declares  the  functions 


memchr{  )* 
memcmp  ()* 
memcpyO* 
memmoue  ()* 
memsetO* 


strcati ) 
strchr( ) 
strcmp  () 
strcollO* 
strcpyi) 


strcspni) 
strerror{ )* 
strleni) 
strncati) 


strncmp  () 
strncpyi) 
strpbrk  () 
strrchr( ) 


<sys/stat .h> 

The  header  defines  the  macros 


S_IRGRP 

S_IRWXO 

SJSCHR 

S_ISGID 

S_IWGRP 

SJROTH 

SJRWXU 

S.ISDIR 

S_ISREG 

S_IWOTH 

SJRUSR 

S_IRWXG 

S_ISBLK 

SJSFIFO 

S_ISUID 

S.IWUSR 

and  declares  the  structure 
stat 

with  structure  elements 

stjatime  stjdev  st_ino  stjntime  st_size 

stjctime  st_gid  stjnode  stjnlink  st_uid 

and  the  functions 


chmod  ()  mkdir()  stat  () 

fstati )  mkfifoi )  umask  ( ) 


<sys/times .h> 

The  header  defines  the  type 


clock  _t 


and  declares  the  structure 


tms 

with  structure  elements 

tmsjcstime  tms_cutime  tms_stime  tms_utime 
and  the  function 
times  () 


strspn  ( ) 
strstr( ) 
strtok () 
strxfrmO* 


S_IXGRP 

SJXOTH 

S_IXUSR 
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240  <sys/types  .h> 

241  The  header  defines  the  types 

242  dev_t  inojt  nlinkjt  pidj  ssize_t 

243  gid_t  modejt  off_t  sizejt  uid_t 

244  <sys/utsname  .h> 

245  The  header  declares  the  structure 

246  utsname 

247  with  structure  elements 

248  machine  nodename  release  sysname  version 

249  and  the  function 


250 

uname  () 

251 

<sys/wait .h> 

252 

The  header  defines  the 

macros 

253 

WEXITSTATUS 

WIFSIGNALED 

WNOHANG 

254 

WIFEXITED 

WIFSTOPPED 

WSTOPSIG 

WTERMSIG 

WUNTRACED 


255  and  declares  the  functions 


256  wait()  waitpidi) 

257  <termios.h> 

258  The  header  defines  the  macros 


259 

B0 

B75 

ECHONL 

NCCS 

TCSAFLUSH 

260 

B110 

B9600 

HUPCL 

NOFLSH 

TCSANOW 

261 

B1200 

BRKINT 

ICANON 

OPOST 

TOSTOP 

262 

B134 

CLOCAL 

ICRNL 

PARENB 

VEOF 

263 

B150 

CREAD 

IEXTEN 

PARMRK 

VEOL 

264 

B1800 

CS5 

IGNBRK 

PARODD 

VERASE 

265 

B19200 

CS6 

IGNCR 

TCIFLUSH 

VINTR 

266 

B200 

CS7 

IGNPAR 

TCIOFF 

VKILL 

267 

B2400 

CS8 

INLCR 

TCIOFLUSH 

VMIN 

268 

B300 

CSIZE 

INPCK 

TCION 

VQUIT 

269 

B38400 

CSTOPB 

ISIG 

TCOFLUSH 

VST  ART 

270 

B4800 

ECHO 

ISTRIP 

TCOOFF 

VSTOP 

271 

B50 

ECHOE 

IXOFF 

TCOON 

VSUSP 

272 

B600 

ECHOK 

IXON 

TCSADRAIN 

VTIME 
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and  the  types 

cc_t  speed  _t  tcflagjt 

and  declares  the  structure 
termios 

with  structure  elements 

c_cc  c_cflag  cjflag  c_lflag  c_oflag 

and  the  functions 

cfgetispeedi)  cfsetospeedO  tcflushO  tcsendbreakO 

cfgetospeedO  tcdrain()  tcgetattr{ )  tcsetattr  () 

cfsetispeed  ( )  tcflow  ( ) 

<time .h> 

The  header  defines  the  macros 

CLKTCK  CLOCKS_PER_SEC  NULL 

the  types 

clock_t  sizej  timej 

and  declares  the  structure 
tm 

with  structure  elements 

tmjiour  tmjnday  tmjnon  tmjuuday  tmjyear 

tm_isdst  tmjnin  tm_sec  tmjyday 

and  the  functions 

asctime  ()  ctime  ()  gmtime  ()  mktime  ()  time() 

clock  ()*  difftime  ()*  localtimeO  strftimei)  tzset() 

and  declares  the  external  variable 

tzname 
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<unistd .h> 

The  header  defines  the  macros 


F_OK 

NULL 

R_OK 

SEEK_CUR 

SEEK_END 

SEEKJ3ET 

STDERR_FILENO 

STDIN.FILENO 

STDOUT_FILENO 

W_OK 

X_OK 

_pc_chown_restricted 

_PC_LINK_MAX 

_PC_MAX_CANON 

_PC_MAX_INPUT 

_PC_NAME_MAX 

_PC_N  0_TRUN  C 

_PC_PATH_MAX 

and  defines  the  types 

sizej*  ssize_t* 

and  declares  the  functions 


PC_PIPE_BUF 

PC_VDISABLE 

POSIX_CHOWN_RESTRICTED 

POSIX_JOB_CONTROL 

POSIX_NO_TRUNC 

POSIX_SAVED_IDS 

POSIX_VDISABLE 

POSIX_VERSION 

SC_ARG_MAX 

SC_CHILD_MAX 

SC_CLK_TCK 

SC_J  OB_CONTROL 

SC_NGROUPS_MAX 

SC_OPEN_MAX 

SC_SAVED_IDS 

SC_STREAM_MAX 

SC_TZNAME_MAX 

SC_VERSION 


_exit( ) 

execl( ) 

geteuidi) 

link() 

setsidO 

access () 

execle  () 

getgidi) 

Iseek  () 

setuid{ ) 

alarm  ( ) 

execlp  () 

getgroupsO 

pathconfi ) 

sleep  () 

chdir( ) 

execvO 

getlogini) 

pause  () 

sysconfi ) 

chown() 

execve () 

getpgrpO 

pipe  () 

tcgetpgrp  () 

close () 

execvp  () 

getpidi) 

read() 

tcsetpgrp  () 

ctermidO 

fork  () 

getppidO 

rmdir() 

tty  name  () 

cuseridi) 

fpathconf{ ) 

getuidi) 

setgidi) 

unlinkO 

dup2( ) 

getcwdO 

isattyO 

setpgidi ) 

write  () 

dup  () 

getegidi) 

NOTE:  The  cuserid{)  symbol  is  permitted  in  this  header,  but  need  not  be  supplied.  See  2.7.2. 


<utime .h> 

The  header  declares  the  structure 
utimbuf 

with  structure  elements 
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336  actime 

337  and  the  function 

338  utime  () 


modtime 


312 


C  Header  Contents  Samples 


1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


Annex  D 

(informative) 

Profiles 


This  standard  contains  a  number  of  options  and  variables  that  reflect  the  range  of 
systems  and  environments  that  might  be  encountered.  In  general,  it  will  be  use¬ 
ful  for  applications  to  take  the  full  range  of  these  possibilities  into  account  and 
either  accommodate  them  or  exclude  them.  However,  there  are  significant  com¬ 
munities  of  interest  that  may  have  common  needs  that  warrant  focusing  on  a 
specific  suite  of  these  options  and  parameters.  This  annex  discusses  the  concept 
of  profiles  (also  known  as  functional  standards )  and  how  they  address  this 
problem. 

This  annex  reflects  current  thinking.  It  is  clear  that  a  concept  such  as  this  will 
help  significantly  in  clarifying  the  intended  use  of  these  standards.  It  is  to  be 
expected  that  some  of  the  details  of  this  material  will  be  changed  before  it  is  fully 
stabilized. 

As  background:  the  OSI  model  has  over  170  standards  (and  consequent  combina¬ 
tions  thereof)  that  fit  within  it.  Only  a  fraction  of  those  are  actually  useful  for  any 
given  application  environment.  The  concept  of  profiles  was  developed  to  address 
this  issue  and  appears  also  to  apply  to  the  area  of  application  portability.  The 
ISO/IEC  term  for  such  profiles  is  ISP,  or  “International  Standardized  Profile.” 


D.l  Definitions 

The  following  definitions  are  proposed  for  use  in  the  area  covered  by  this  part  of 
ISO/IEC  9945. 

D.1.1  Applications  Environment  Profile  (AEP)  [profile]:  The  specification  of 
a  complete  and  coherent  subset  of  an  Open  System  Environment,  together  with 
the  options  and  parameters  necessary  to  support  a  class  of  applications  for  intero¬ 
perability  or  applications  portability,  including  consistency  of  data  access  and 
human  interfaces.  Where  there  are  several  AEPs  for  the  same  OSE,  they  are  har¬ 
monized. 

AEPs  are  the  basis  for  procurement  and  conformance  testing  and  are  the  target 
environment  for  software  development. 

D.1.2  Application  Specific  Environment  (ASE):  A  complete  and  coherent 
subset  of  an  Applications  Environment  Profile,  together  with  interfaces,  services, 
or  supporting  formats  outside  of  the  profile,  that  are  required  by  a  particular 


D.l  Definitions 


313 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


INFORMATION  TECHNOLOGY— POSIX 


32  application  for  its  installation  and  execution. 

33  D.1.3  Application  Specific  Environment  Description  (ASED):  The 

34  specification  of  an  Application  Specific  Environment,  together  with  the  specific 

35  options  or  parameters  required;  interfaces,  services,  or  supporting  formats  outside 

36  of  the  profile;  and  resource  requirements  necessary  for  the  satisfactory  operation 

37  of  the  application.  (For  example,  storage  and  performance  requirements.) 

38  (This  term  is  intended  for  use  in  Applications  Conformance  clauses  found  in 

39  profiles.) 

40  D.1.4  coherent:  The  parts  are  logically  connected.  (For  example,  if  both  FOR- 

41  TRAN  and  COBOL  are  specified,  whether  they  can  share  files  is  specified.) 

42  D.1.5  complete:  Having  all  the  necessary  parts.  (For  example,  if  COBOL  and 

43  SQL  are  both  specified,  then  there  is  a  COBOL  binding  to  SQL,  or  at  least  an  expla- 

44  nation  of  why  not.) 

45  D.1.6  comprehensive:  A  sufficiently  broad  range  of  functionality  is  covered 

46  that  the  needs  of  most  Applications  Environment  Profiles  are  met. 

47  D.1.7  consistent:  The  parts  of  the  Open  System  Environment  do  not  inherently 

48  conflict  with  each  other.  This  does  not  preclude  options  that  conflict,  as  long  as 

49  an  Applications  Environment  Profile  can  select  a  set  that  does  not  conflict. 

so  D.1.8  harmonized:  Where  same  functionality  is  needed  in  several  profiles,  it 

51  appears  identically  in  all  of  them. 

52  D.1.9  Open  System  Environment  (OSE):  A  comprehensive  and  consistent  set 

53  of  international  information  technology  standards  and  functional  standards 

54  (profiles)  that  specify  interfaces,  services,  and  supporting  formats  to  accomplish 

55  interoperability  and  portability  of  applications,  data,  and  people.  These  are  based 

56  on  International  Standards  (ISO,  IEC,  CCITT, . . . ) 

57  D.1.10  POSIX  Open  System  Environment:  A  comprehensive  and  consistent 

58  set  of  ISO/IEC,  regional,  and  national  information  technology  standards  and  func- 

59  tional  standards  (profiles)  that  specify  interfaces,  services,  and  supporting  for- 

60  mats  for  interoperability  and  portability  of  applications,  data,  and  people  that  are 

61  in  accord  with  ISO/IEC  9945  (POSIX). 

62  No  single  component  of  the  OSE,  including  ISO/IEC  9945,  is  expected  to  be 

63  required  in  all  such  profiles. 


64  D.2  Options  in  This  Part  of  ISO/IEC  9945 

65  In  terms  of  this  part  of  ISO/IEC  9945,  there  are  a  number  of  features  that  could  be 

66  specified  in  a  profile.  This  list  includes: 

67  —  The  options  listed  in  1.3. 1.3. 

68  —  The  limits  in  2.8.  Regarding  the  the  C  Language  Limits  for  the  type  char , 

69  care  should  be  taken  that  those  limits  are  not  for  the  POSIX.  1  definition  of 

70  character,  but  for  the  one  in  the  C  language.  For  the  POSIX.  1  definition  of 
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71 

72 


character,  the  following  limits  from  the  C  Standard  {2}  could  be  specified  as  | 
well:  {MB_LEN_MAX}  and  {MB_CUR_MAX}. 


73 


—  The  flags  in  2.9.4. 


75 

76 

77 


74 


—  Instances  of  the  word  “may”  throughout  the  document.  (Note  that  not  all  | 
instances  of  “may”  constitute  behavior  that  could  or  should  be  considered  | 
appropriate  for  specification  in  a  profile.  Some  reflect  implementation  vari-  | 
ants  that  should  not  matter  to  applications.) 


81 

82 


80 


78 


79 


—  Features  that  are  specified  in  a  generic  way  for  broad  portability  of  the  | 
standard,  that  might  reasonably  be  constrained  in  the  more  limited  context  | 
of  a  profile.  For  such  features,  the  constraint  shall  be  documented  in  a  | 
profile  so  that  the  effects  of  the  constraint  on  the  standard  would  be  | 
clarified. 


83  D.3  Related  Standards  | 

84  The  other  POSIX  standards  (ISO/IEC  9945-2  {B36},  in  particular)  are  expected  to  | 

85  form  a  major  part  of  the  POSIX  OSE.  Other  formal  standards,  such  as  those  listed  | 

86  in  Annex  A,  are  also  expected  to  be  part  of  such  a  document  (in  particular,  the  | 

87  C  Standard  {2}.)  j 

88  Standards  such  as  other  languages,  SQL,  graphics  standards  such  as  GKS,  and  | 

89  networking  standards  are  also  probable  candidates  for  inclusion  in  the  POSIX  | 

90  OSE. 


91  D.4  Related  Activities  | 

92  In  many  ways,  the  work  of  NIST  (in  terms  of  FIPS),  OSF,  UNIX  International,  and  | 

93  X/Open  often  act  like  early  (but  sophisticated)  profiles  or  metaprofiles,  specifying  | 

94  a  range  of  standards  from  which  true  profiles  could  select.  They  collect  together  | 

95  many  standards,  specify  options,  and  specify  the  relationship  between  the  parts.  | 

96  These  activities  go  well  beyond  profiles,  as  they  add  specifications  that  are  not  for-  | 

97  mal  standards  to  the  suite  as  well.  Often  these  additional  specifications  point  to  | 

98  areas  where  formal  standards  are  required. 


99  D.5  Relationship  to  IEEE  Draft  Project  1003.0  I 

100  The  IEEE  P1003.0  working  group  is  writing  a  Guide  to  Open  Systems.  In  many  | 

101  ways,  this  is  the  specification  of  the  POSIX  Open  Systems  Environment.  It  could  | 

102  be  the  specification  of  the  collection  of  standards  that  might  be  used  to  specify  | 

103  many  Open  Systems  Environments,  depending  on  how  exactly  that  work  | 

104  proceeds.  I 
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Annex  E 

(informative) 

Sample  National  Profile 


One  class  of  “community  of  interest”  for  which  profiles  (as  discussed  in  Annex  D) 
are  useful  is  specific  countries,  where  the  general  characteristics  warrant  specific 
focus  to  serve  the  needs  of  users  in  those  countries.  Such  needs  lead  to  a  number 
of  implications  concerning  the  options  available  within  this  part  of  ISO/IEC  9945 
and  may  warrant  specification  of  complementary  standards  as  well. 

The  following  is  an  example  of  a  country’s  needs  with  respect  to  this  part  of 
ISO/IEC  9945  and  how  those  needs  relate  to  other  international  standards  as  well 
as  national  standards.  The  example  provided  is  included  here  for  informative 
purposes  and  is  not  a  formal  standard  in  the  country  in  question.  It  is  provided 
by  the  Danish  Standards  Association  and  is  as  accurate  as  possible  with  regards 
to  Danish  needs. 1)  This  example  national  profile  is  worded  as  if  it  were  a  national 
standard. 

A  subclass  of  conforming  implementations  can  be  identified  that  meet  the  require¬ 
ments  of  a  specific  profile.  By  documenting  these  either  in  national  standards,  in 
a  document  similar  to  an  ISO/IEC  ISP  (an  International  Standardized  Profile),  or 
in  an  informative  annex  (such  as  this),  these  can  be  referenced  in  a  consistent 
manner. 


1)  Further  information  may  be  obtained  from  the  Danish  Standards  Association,  Attn:  Sl42u22All 
POSIX  WG,  Box  77,  DK-2900  Hellerup,  Denmark;  FAX:  +45  31  62  30  77;  Email:  posix@itc .  dk 

The  data  is  also  available  electronically  by  anonymous  FTAM  or  FTP  at  the  site  dkuug .  dk  in  the 
directory  isp,  where  some  other  example  national  profiles,  locales,  and  charmaps  may  also  be 
found.  They  are  also  available  by  an  archive  server  reached  at  archive@dkuug.dk;  use 
“Subject :  help”  for  further  information. 

More  complete  examples  of  profiles  are  expected  to  be  available  in  future  revisions  of  this  part  of 
ISO/IEC  9945  and  in  other  POSIX  standards. 


Annex  E  Sample  National  Profile 


317 


ISO/IEC  9945-1:  1990 
IEEE  Std  1003.1-1990 


INFORMATION  TECHNOLOGY— POSIX 


26  E.l  (Example)  Profile  for  Denmark 

27  NOTE:  This  profile  is  chosen  both  for  its  instructive  value  by  being  a  European  profile  and  the  gen- 

28  erality  in  the  provisions  it  makes,  addressing  most  of  the  relevant  points.  It  does  claim  to  be  correct 

29  for  Denmark,  and  the  style  is  what  would  be  expected  in  a  real  ISP.  A  collection  of  real  ISPs  would 

30  be  as  useful,  and  work  is  underway  collecting  these. 

31  This  is  the  definition  of  the  Danish  Standards  Association  POSIX.  1  profile.  Infor- 

32  mation  on  the  actual  data  for  the  locale  and  coded  character  set  mapping 

33  definitions  are  under  development  as  part  of  an  informative  annex  in 

34  ISO/IEC  9945-2  {B36}.2) 

35  The  subset  of  conforming  implementations  that  provide  the  required  characteris- 

36  tics  below  is  referred  to  as  conforming  to  the  “Danish  Standards  Association  (DS) 

37  Environment  Profile”  for  this  part  of  ISO/IEC  9945. 

38  The  profile  specifies  no  options  according  to  POSIX.l  section  2.9.3.  For  section 

39  2.8.4  in  the  <limits.h>  specification,  the  LPOSIX_TZNAME_MAX}  value  shall 

40  be  7. 


41  E.1.1  Character  Encoding 

42  Any  character  encoding  with  the  required  repertoire  of  the  POSIX  profile  plus  the 

43  following  repertoire  shall  be  allowed. 

44  A  “character  set  description  file,”  as  described  in  ISO/IEC  9945-2,  {B36}  shall  use 

45  the  symbolic  character  names  of  the  iso_10  64  6  charmap  file  described  in  the 

46  ISO/IEC  9945-2  {B36}  sample  profile  annex  for  the  characters  encoded  in  the  char- 

47  acter  set. 

48  For  the  Danish  and  Greenlandic  languages,  the  following  characters  shall  be 

49  present  in  addition  to  the  repertoire  required  by  the  POSIX  profile:  <ae>,  <o/>, 

50  <aa>,  <ae>,  <0/ >,  and  <aa>.  For  the  Faroese  language,  the  following  characters 

51  shall  be  present  in  addition  to  the  required  POSIX  locale  characters  and  Danish 

52  repertoire:  <a'>,  <i'>,  <o'>,  <u'>,  <y'>,  <d->,  <A' >,  <!' >,  <0'>,  <U'>, 

53  <Y'  >,  and  <D— >. 

54  Recommended  character  sets  are  ISO  8859-1  {B34}  or  ISO  10646  {B37}.  The 

55  CHARSET  environment  variable  shall  be  used  to  specify  the  processing  character 

56  set;  for  instance,  iso_88  59-l  or  iso_1064  6.  This  shall  be  used  to  select  the 

57  encoded  character-set-specific  versions  of  the  locale  definitions.  If  no  CHARSET 

58  variable  is  present,  iso_88  5  9-l  shall  be  assumed. 


59  2)  The  9945-2  document,  “POSIX.2,”  is  currently  in  the  state  of  a  Committee  Document  (CD),  to  be 

60  approved  as  a  Draft  International  Standard. 
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E.1.2  Character  Encoding  and  Display 

For  terminal  equipment  not  capable  of  generating  or  showing  the  processing  char¬ 
acter  set,  the  character  names  defined  in  the  current  charmap  file  shall  be  used: 
characters  in  the  charmap  file  having  two-character  names  shall  be  specified  by 
the  two-character  name  preceded  by  the  <intro>  character,  and  characters  hav¬ 
ing  charmap  names  longer  than  two  characters  shall  be  specified  by  the  character 
name  preceded  by  the  <intro>  character  and  an  <underline>  and  followed  by 
an  <underline>.  In  names  longer  than  two  characters,  an  <intro>  character 
and  an  <underline>  character  in  sequence  shall  signify  a  literal  <underline> 
character  part  of  the  character  name.  Two  <intro>  characters  in  sequence  shall 
signify  one  < intro  character,  both  in  names  and  in  the  general  stream. 

For  input,  if  the  character  name  is  undefined  in  the  current  charmap  file,  the  data 
shall  be  left  untouched  (including  the  <intro>  character)  and  the  behavior  is 
implementation  defined. 


E.1.3  Locale  Definitions 

The  following  guideline  is  used  for  specifying  the  locale  identification  string:3) 

"%2 . 2s_%2 . 2s  .  %s,  %s",  <language>,  <territory>,  <character-set>, 
<version> 

where  <language>  shall  be  taken  from  ISO  639  {B32}  and  <territory>  shall  be  the 
two-letter  country  code  of  ISO  3166  {B33},  if  possible.  The  <language>  shall  be 
specified  with  lowercase  letters  only,  and  the  <territory>  shall  be  specified  in 
uppercase  letters  only.  An  optional  <character-set>  specification  may  follow  after 
a  <period>  for  the  name  of  the  character  set;  if  just  a  numeric  specification  is 
present,  this  shall  represent  the  number  of  the  international  standard  describing 
the  character  set.  If  the  <character-set>  specification  is  not  present,  the  encoded 
character  set  specific  locale  shall  be  determined  by  the  CHARSET  environment 
variable,  and  if  this  is  unset  or  null,  the  encoding  of  ISO  8859-1  {B34}  shall  be 
assumed.  A  parameter  specifying  a  <version>  of  the  profile  may  be  placed  after 
the  optional  <character-set>  specification,  delimited  by  <comma>.  This  may  be 
used  to  discriminate  between  different  cultural  needs;  for  instance,  dictionary 
order  versus  a  more  systems-oriented  collating  order. 

Following  the  above  guidelines  for  locale  names,  the  national  Danish  locale  string 
shall  be 

daJDK 

In  the  following,  the  TZ  variable  shall  be  specified  according  to  the  current  official 
daylight-saving-time  rules  in  Denmark.  Since  Daylight  Saving  Time  is  politically 
decided  and  thus  changeable,  this  is  only  a  recommendation. 


3)  The  guideline  was  inspired  by  the  XI Open  Portability  Guide  {B61}.  It  is  presented  in  the  file 
format  notation  used  by  ISO/IEC  9945-2  {B36}. 
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The  locale  definition  for  Denmark  shall  be  as  follows: 

LANG  da_DK 

TZ  CET-1CET  DST,M3 . 5 .0/M9 .5.0 

The  locale  definition  for  the  Faroe  Islands  shall  be  as  follows: 

LANG  fo_DK 

TZ  UTCOUTC  dst,M3 . 5 . 0/M9 . 5 . 0 

The  locale  definition  for  Western  Greenland  shall  be  as  follows: 

LANG  kl_DK 

TZ  utz+3vtz,M3 . 5 . 0/M9 . 5 . 0 

The  locale  definition  for  Eastern  Greenland  shall  be  as  follows: 

LANG  kl_DK 

TZ  vtz  +  2wtz,  M3 . 5 . 0/M9 . 5 . 0 

For  the  Faroe  Islands  and  Greenland,  only  the  LC_TIME  and  LC_MESSAGES 
data  are  different  from  the  Danish  language  specifications. 
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Identifier  Index 

abort()  Referenced  C  Language  Routines  {8.1}  .  151 

abs( )  Referenced  C  Language  Routines  {8.1} .  151 

access ()  Check  File  Accessibility  {5.6.3}  .  104 

acos ()  Referenced  C  Language  Routines  {8.1} .  151 

alarm()  Schedule  Alarm  {3.4.1}  .  63 

asctime ()  Extensions  to  Time  Functions  {8.1.1}  .  152 

asin{)  Referenced  C  Language  Routines  {8.1} .  151 

assertO  Referenced  C  Language  Routines  {8.1} .  151 

atari  ()  Referenced  C  Language  Routines  {8.1} .  151 

atan2{)  Referenced  C  Language  Routines  {8.1} .  151 

atofi )  Referenced  C  Language  Routines  {8.1} .  151 

atoi()  Referenced  C  Language  Routines  {8.1} .  151 

atol{)  Referenced  C  Language  Routines  {8.1} .  151 

bsearchi)  Referenced  C  Language  Routines  {8.1} .  151 

calloc  ()  Referenced  C  Language  Routines  {8.1} .  151 

ceil()  Referenced  C  Language  Routines  {8.1} .  151 

cfgetispeedO  Baud  Rate  Functions  {7.1.3}  .  141 

cfgetospeedi)  Baud  Rate  Functions  {7.1.3}  .  141 

cfsetispeedO  Baud  Rate  Functions  {7.1.3}  .  141 

cfsetospeed()  Baud  Rate  Functions  {7.1.3}  .  141 

chdir()  Change  Current  Working  Directory  {5.2.1}  .  86 

chmodO  Change  File  Modes  {5.6.4}  .  106 

chown ()  Change  Owner  and  Group  of  a  File  {5.6.5}  .  107 

clearerr ()  Referenced  C  Language  Routines  {8.1} .  151 

close ()  Close  a  File  {6.3.1}  .  115 

closedir()  Directory  Operations  {5.1.2}  .  83 

cos()  Referenced  C  Language  Routines  {8.1} .  151 

cosh ()  Referenced  C  Language  Routines  {8.1} .  151 

cpio  Extended  cpio  Format  {10.1.2} .  173 

creat()  Create  a  New  File  or  Rewrite  an  Existing  One  {5.3.2} .  91 

ctermidO  Generate  Terminal  Pathname  {4.7.1}  .  78 

dime ()  Referenced  C  Language  Routines  {8.1} .  152 

devjt  Primitive  System  Data  Types  {2.5} .  27 

directory  Directory  Operations  {5.1.2}  .  83 

<dirent.h>  Format  of  Directory  Entries  {5.1.1}  .  83 

dup()  Duplicate  an  Open  File  Descriptor  {6.2.1} .  114 

dup2{)  Duplicate  an  Open  File  Descriptor  {6.2.1} .  114 

environ  Execute  a  File  {3.1.2}  .  42 

errno  Error  Numbers  {2.4} .  23 

<errno.h>  Error  Numbers  {2.4} .  23 

exec  Execute  a  File  {3.1.2}  .  42 

execl()  Execute  a  File  {3.1.2}  .  42 

execle ()  Execute  a  File  {3.1.2}  .  42 

execlpO  Execute  a  File  {3.1.2}  .  42 

execv ()  Execute  a  File  {3.1.2}  .  42 

execve ()  Execute  a  File  {3.1.2}  .  42 
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execvpO  Execute  a  File  {3.1.2}  .  42 

exit()  Referenced  C  Language  Routines  {8.1} .  151 

_exit()  Terminate  a  Process  {3.2.2}  .  49 

exp  ()  Referenced  C  Language  Routines  {8.1} .  151 

fabs()  Referenced  C  Language  Routines  {8.1} .  151 

fcloseO  Referenced  C  Language  Routines  {8.1} .  151 

fcnttt)  File  Control  {6.5.2}  .  121 

<f  cnt  l .  h>  Data  Definitions  for  File  Control  Operations  {6.5.1} .  121 

fdopenO  Open  a  Stream  on  a  File  Descriptor  {8.2.2}  .  157 

feofi)  Referenced  C  Language  Routines  {8.1} .  151 

ferrorO  Referenced  C  Language  Routines  {8.1} .  151 

fflushO  Referenced  C  Language  Routines  {8.1} .  151 

fgetc ()  Referenced  C  Language  Routines  {8.1} .  151 

fgets()  Referenced  C  Language  Routines  {8.1} .  151 

filenoi)  Map  a  Stream  Pointer  to  a  File  Descriptor  {8.2.1}  .  156 

floor()  Referenced  C  Language  Routines  {8.1} .  151 

fmod()  Referenced  C  Language  Routines  {8.1} .  151 

fopen  ()  Referenced  C  Language  Routines  {8.1} .  151 

fork ()  Process  Creation  {3.1.1}  .  41 

fpathconfO  Get  Configurable  Pathname  Variables  {5.7.1}  .  110 

fprintfi)  Referenced  C  Language  Routines  {8.1} .  151 

fputc  ()  Referenced  C  Language  Routines  {8.1} .  151 

fputs()  Referenced  C  Language  Routines  {8.1} .  151 

fread()  Referenced  C  Language  Routines  {8.1} .  151 

free ()  Referenced  C  Language  Routines  {8.1} .  151 

freopen ()  Referenced  C  Language  Routines  {8.1} .  151 

frexp ()  Referenced  C  Language  Routines  {8.1} .  151 

fscanfi)  Referenced  C  Language  Routines  {8.1} .  151 

fseek  ()  Referenced  C  Language  Routines  {8.1} .  151 

fstati)  Get  File  Status  {5.6.2}  .  103 

ftellO  Referenced  C  Language  Routines  {8.1} .  151 

fwrite  ()  Referenced  C  Language  Routines  {8.1} .  151 

getc ()  Referenced  C  Language  Routines  {8.1} .  151 

getchar()  Referenced  C  Language  Routines  {8.1} .  151 

getcwdO  Get  Working  Directory  Pathname  {5.2.2}  .  87 

getegidi)  Get  Real  User,  Effective  User,  Real  Group,  and  Effective 

Group  IDs  {4.2.1}  .  68 

getenv ()  Environment  Access  {4.6.1} .  77 

geteuidO  Get  Real  User,  Effective  User,  Real  Group,  and  Effective 

Group  IDs  {4.2.1}  .  68 

getgidO  Get  Real  User,  Effective  User,  Real  Group,  and  Effective 

Group  IDs  {4.2.1}  .  68 

getgrgidO  Group  Database  Access  {9.2.1}  .  166 

getgrnamO  Group  Database  Access  {9.2.1}  .  166 

getgroups ()  Get  Supplementary  Group  IDs  {4.2.3}  .  70 

getloginO  Get  User  Name  {4.2.4}  .  71 

getpgrp  ()  Get  Process  Group  ID  {4.3.1}  .  72 

getpidO  Get  Process  and  Parent  Process  IDs  {4.1.1}  .  67 

getppid()  Get  Process  and  Parent  Process  IDs  {4.1.1}  .  67 

getpwnamO  User  Database  Access  {9.2.2}  .  167 

getpwuidi)  User  Database  Access  {9.2.2}  .  167 
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gets()  Referenced  C  Language  Routines  {8.1} .  151 

getuidi)  Get  Real  User,  Effective  User,  Real  Group,  and  Effective 

Group  IDs  {4.2.1}  .  68 

gidjt  Primitive  System  Data  Types  {2.5} .  27 

gmtime ()  Referenced  C  Language  Routines  {8.1} .  152 

<grp.h>  Group  Database  Access  {9.2.1}  .  166 

ino_t  Primitive  System  Data  Types  {2.5} .  27 

isalnumO  Referenced  C  Language  Routines  {8.1} .  151 

isalphai)  Referenced  C  Language  Routines  {8.1} .  151 

isatty ()  Determine  Terminal  Device  Name  {4.7.2} .  79 

iscntrlO  Referenced  C  Language  Routines  {8.1} .  151 

isdigiti)  Referenced  C  Language  Routines  {8.1} .  151 

isgraphi)  Referenced  C  Language  Routines  {8.1} .  151 

islower()  Referenced  C  Language  Routines  {8.1} .  151 

isprint ()  Referenced  C  Language  Routines  {8.1} .  151 

ispunct ()  Referenced  C  Language  Routines  {8.1} .  151 

isspace  ()  Referenced  C  Language  Routines  {8.1} .  151 

isupperO  Referenced  C  Language  Routines  {8.1} .  151 

isxdigiti)  Referenced  C  Language  Routines  {8.1} .  151 

kill()  Send  a  Signal  to  a  Process  {3.3.2}  .  56 

IdexpO  Referenced  C  Language  Routines  {8.1} .  151 

< limits . h>  Numerical  Limits  {2.8}  .  34 

link ()  Link  to  a  File  {5.3.4} .  92 

localtime ()  Referenced  C  Language  Routines  {8.1} .  152 

log ()  Referenced  C  Language  Routines  {8.1} .  151 

log  10 ()  Referenced  C  Language  Routines  {8.1} .  151 

longjmp  ()  Referenced  C  Language  Routines  {8.1} .  151 

Iseek ()  Reposition  Read/Write  File  Offset  {6.5.3}  .  127 

main()  Description  {3. 1.2.2}  .  43 

malloc ()  Referenced  C  Language  Routines  {8.1} .  151 

mkdir()  Make  a  Directory  {5.4.1}  .  94 

mkfifoO  Make  a  FIFO  Special  File  {5.4.2} .  95 

mktime ()  Referenced  C  Language  Routines  {8.1} .  152 

modej  Primitive  System  Data  Types  {2.5} .  27 

modf()  Referenced  C  Language  Routines  {8.1} .  151 

nlinkjt  Primitive  System  Data  Types  {2.5} .  27 

off_t  Primitive  System  Data  Types  {2.5} .  27 

open{)  Open  a  File  {5.3.1}  .  88 

opendir()  Directory  Operations  {5.1.2}  .  83 

pathconfO  Get  Configurable  Pathname  Variables  {5.7.1}  .  110 

pause ()  Suspend  Process  Execution  {3.4.2}  .  64 

perror ()  Referenced  C  Language  Routines  {8.1} .  151 

pidj  Primitive  System  Data  Types  {2.5} .  27 

pipe ()  Create  an  Inter-Process  Channel  {6.1.1}  .  113 

pow()  Referenced  C  Language  Routines  {8.1} .  151 

print f()  Referenced  C  Language  Routines  {8.1} .  151 

putc ()  Referenced  C  Language  Routines  {8.1} .  151 

putchar()  Referenced  C  Language  Routines  {8.1} .  151 

puts{)  Referenced  C  Language  Routines  {8.1} .  151 

<pwd.h>  User  Database  Access  {9.2.2}  .  167 

qsortO  Referenced  C  Language  Routines  {8.1} .  151 
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rand()  Referenced  C  Language  Routines  {8.1} .  151 

read()  Read  from  a  File  {6.4.1} .  116 

readdirO  Directory  Operations  {5.1.2}  .  83 

realloc  ()  Referenced  C  Language  Routines  {8.1} .  151 

remove ()  Referenced  C  Language  Routines  {8.1} .  151 

rename ()  Rename  a  File  {5.5.3}  .  99 

rewindO  Referenced  C  Language  Routines  {8.1} .  151 

rewinddir()  Directory  Operations  {5.1.2}  .  83 

rmdir()  Remove  a  Directory  {5.5.2} .  98 

scanfi)  Referenced  C  Language  Routines  {8.1} .  151 

setbufO  Referenced  C  Language  Routines  {8.1} .  151 

setgidO  Set  User  and  Group  IDs  {4.2.2}  .  68 

setjmpi)  Referenced  C  Language  Routines  {8.1} .  151 

setlocale ()  Extensions  to  setlocale{ )  Function  {8.1.2}  .  154 

setpgidO  Set  Process  Group  ID  for  Job  Control  {4.3.3}  .  73 
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Execute  a  File  . . .  42,  228 
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File  Descriptor  Manipulation  ...  114,265 
file  descriptor 

definition  of  ...  14 
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G 

General  Concepts  ...  21,  208 
General  File  Creation  ...  88,257 
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Get  Process  and  Parent  Process  IDs  ...  67, 
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Get  System  Name  ...  74 
Get  System  Time  ...  75,  249 
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gr_gid  ...  166,303 
grjnem  ...  166,303 
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127,  129-132,  134-141,  145,  152,  159,  162, 
165,  169,  171,  175-177,  185,  198-199,  201, 
206-209,  211-213,  218,  230,  232,  235-236, 
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Language-Specific  Services  for  the  C  Program¬ 
ming  Language  ...  151,283 
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mance,  system  purchasers  can  produc¬ 
tively  manage  their  software  environments 
to  achieve  the  benefits  of  applications 
portability.  Likewise,  hardware  and  soft¬ 
ware  suppliers  and  developers  will  have  a 
clear  specification  to  follow  in  designing 
their  systems  and  applications  for  the 
open  software  environment. 

POSIX.1  constitutes  a  major  step  in  the 
industry  toward  providing  a  comprehen¬ 
sive  standardized  applications  environ¬ 
ment.  The  IEEE’s  POSIX  Committee  is 
continuing  POSIX-related  standards  work 
in  areas  such  as  POSIX-based  Open  Sys¬ 
tem  Environment  (IEEE  Project  1003.0), 
Shell  and  Utilities  (IEEE  Project  1003.2), 
Test  Methods  (IEEE  Project  1003.3),  Real- 
Time  Systems  Interfaces  (IEEE  Project 
1003.4),  An  Ada  Language  Binding  for 
POSIX  (IEEE  Project  1003.5),  and  a  FOR¬ 
TRAN  Language  Binding  to  POSIX  (IEEE 
Project  1003.9). 

UNIX  is  a  registered  trademark  of  UNIX  System 
Laboratories  in  the  U  S.  and  other  countries 
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nization,  or  evaluate  functional,  performance,  and  integrity  requirements,  be  sure  to  regis¬ 
ter  for  the  new  IEEE  POSIX  Seminar. 

In  Spring  1991,  IEEE  is  launching  a  2-day  seminar  based  on  the  IEEE  Project  1003.0, 
Guide  to  POSIX  Open  Systems  Environments,  and  other  IEEE  projects  concerning  open 
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Box  1331,  Piscataway,  NJ  08855-1331  USA. 
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ISO/IEC  9945-1  : 1990  (POSIX  .1)  defines 
a  standard  operating  system  interface  and 
environment  based  on  the  UNIX  Operating 
System.  It  supports  applications  portability 
at  the  source-code  level  between  multi¬ 
vendor  computer  systems. 

POSIX.1  establishes  a  set  of  basic  ser¬ 
vices  fundamental  to  the  efficient  con¬ 
struction  of  applications  programs.  Access 
to  these  services  is  provided  through  an 
operating  system  using  the  C  program¬ 
ming  language.  The  OS  interface  estab¬ 
lishes  standard  semantics  and  syntax,  and 
allows  for  application  developers  to  design 
portable  applications. 

Complementing  existing  standards  relat¬ 
ed  to  computer  languages,  database 
management,  and  computer  graphics, 
POSIX.1  is  designed  for  and  used  by  both 
application  developers  and  system  imple¬ 
mentors.  It  provides  a  solid  base  for  the 
systems  procurement  and  evaluation  pro¬ 
cesses.  By  specifying  POSIX.1  confor- 


